{"id":21800923,"url":"https://github.com/vgloic/hardhat-soko","last_synced_at":"2026-02-01T23:02:21.448Z","repository":{"id":251572780,"uuid":"837805187","full_name":"VGLoic/hardhat-soko","owner":"VGLoic","description":"Hardhat plugin for managing compilation artifacts","archived":false,"fork":false,"pushed_at":"2024-10-27T14:43:43.000Z","size":186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-24T08:58:16.045Z","etag":null,"topics":["devops","ethereum","smart-contracts","web3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VGLoic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-04T04:57:16.000Z","updated_at":"2024-10-28T01:55:51.000Z","dependencies_parsed_at":"2024-08-04T06:24:36.553Z","dependency_job_id":"da38b194-5025-4607-aa80-d0c75a905785","html_url":"https://github.com/VGLoic/hardhat-soko","commit_stats":null,"previous_names":["vgloic/hardhat-soko"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/VGLoic/hardhat-soko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VGLoic%2Fhardhat-soko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VGLoic%2Fhardhat-soko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VGLoic%2Fhardhat-soko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VGLoic%2Fhardhat-soko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VGLoic","download_url":"https://codeload.github.com/VGLoic/hardhat-soko/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VGLoic%2Fhardhat-soko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28993747,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T22:01:47.507Z","status":"ssl_error","status_checked_at":"2026-02-01T21:58:37.335Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","ethereum","smart-contracts","web3"],"created_at":"2024-11-27T11:15:06.810Z","updated_at":"2026-02-01T23:02:21.433Z","avatar_url":"https://github.com/VGLoic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hardhat Soko\n\nHardhat plugin in order to manage your smart contract compilation artifacts.\n\n1. [Motivation](#motivation),\n2. [Installation](#installation),\n3. [Configuration](#configuration),\n4. [Projects, tags and IDs](#projects-tags-and-ids),\n5. [Hardhat Tasks](#tasks),\n6. [Using the typings](#using-the-typings),\n7. [Integration examples](#integration-examples).\n\n## Motivation\n\nWhen compiling the smart contracts, the developer will generate _compilation artifacts_. They will contain all the needed informations for further tasks such as deployment, verification or contract interactions.\n\nThese compilation artifacts are often ignored and not commited nor stored. At best, compilation artifact for a contract is contained within its deployment summary. Not having a clear way of identifying or re-using an artifact is a painful experience for all developers working closely or remotely with the smart contracts:\n\n- the smart contract developer, when developing new features, is afraid of erasing artifacts that are still needed,\n- the \"smart contract devops\" has to execute the deployment or interaction scripts with artifact that are meant to be thrown away, it complexifies drastically the sharing of ABIs and deployments to the rest of the team,\n- the developer using the deployed smart contracts often ends up copy pasting deployed addresses and ABIs without having a clear vision on it.\n\n**The goal of this plugin is to encourage the developer to organize the compilation artifacts by releases, hence freezing them once created. These artifacts would be stored on a dedicated storage in order to enable an easy conservation and retrieval.**\n\nOnce the artifacts are kept safe on the storage, developers can easily leverage them in order to execute the same tasks as before but in a safer and clearer way:\n\n- deployment scripts depend only on frozen artifacts,\n- the artifact associated to a deployed contract can be easily found, hence allowing verification or interaction,\n- pipelines can be built using the stored artifacts in order to expose safely to other developers the ABIs and the deployed contracts.\n\n## Installation\n\nInstallation can be made using any package manager\n\n```bash\nnpm install hardhat-soko\n```\n\n```bash\npnpm install hardhat-soko\n```\n\n```bash\nyarn add hardhat-soko\n```\n\n## Configuration\n\nIn the `hardhat.config.ts/js` file, one should import the `hardhat-soko` plugin and fill the Soko configuration.\n\n```ts\nimport { HardhatUserConfig } from \"hardhat/config\";\nimport \"@nomicfoundation/hardhat-toolbox\";\n...\nimport \"hardhat-soko\";\n\nexport const config: HardhatUserConfig = {\n  ... // Existing configuration\n  // Example configuration for Soko with AWS S3 as storage for compilation artifacts\n  soko: {\n    project: \"awesome-stuff\",\n    pulledArtifactsPath: \".soko\",\n    typingsPath: \".soko-typings\",\n    storageConfiguration: {\n      type: \"aws\",\n      awsRegion: AWS_REGION,\n      awsBucketName: AWS_S3_BUCKET,\n      awsAccessKeyId: AWS_ACCESS_KEY_ID,\n      awsSecretAccessKey: AWS_SECRET_ACCESS_KEY,\n    },\n  },\n}\n```\n\nHere is the detailled TypeScript type of the configuration\n\n```ts\ntype SokoHardhatUserConfig = {\n  // The name of the project\n  project: string;\n  // Local path in which artifacts will be pulled\n  // Default to `.soko`\n  pulledArtifactsPath?: string;\n  // Local path in which typings will be generated\n  // Default to `.soko-typings`\n  typingsPath?: string;\n  // Configuration of the storage where the artifacts will be stored\n  // Only AWS is supported for now\n  storageConfiguration: {\n    type: \"aws\";\n    awsRegion: string;\n    awsBucketName: string;\n    awsAccessKeyId: string;\n    awsSecretAccessKey: string;\n  };\n  // If enabled, all tasks are running with activated debug mode\n  // Default to `false`\n  debug?: boolean;\n};\n```\n\n## Projects, tags and IDs\n\n**An ID, e.g. `123456789abcdef`, is derived for each compilation artifact**. The ID is based on the content of the artifact.\n\n**A tag, e.g. `v1.2.3`, can be associated to a compilation artifact when pushed.**\n\n**A project, e.g. `my-project`, will gather many compilation artifacts.**\n\nA project is setup at the level of the Hardhat Config, it will be used when pushing new artifacts or as default for the other commands. It is however possible to pull any projects you control.\n\n## Tasks\n\n\u003e [!NOTE]\n\u003e The code snippets in this section uses `npx` but one can choose something else\n\nAn overview of the Soko tasks is exposed by running the `soko` task:\n\n```bash\nnpx hardhat soko\n```\n\nHelp about any task scopped under soko is available:\n\n```bash\nnpx hardhat help soko push\n```\n\n### Push\n\nPush a local compilation artifact for the configured project to the storage, creating the remote artifact with its ID and optionally tagging it.\n\nOnly push the compilation artifact without an additional tag:\n\n```bash\nnpx hardhat soko push --artifact-path ./path/to/my/artifact.json\n```\n\nOr use a tag to associate the compilation artifact with it\n\n```bash\nnpx hardhat soko push --artifact-path ./path/to/my/artifact.json --tag v1.2.3\n```\n\n### Pull\n\nPull locally the missing artifacts from the configured storage.\n\nOne can pull all the artifacts from the configured project\n\n```bash\nnpx hardhat soko pull\n```\n\nOr target a specific artifact using its tag or ID or another project:\n\n```bash\nnpx hardhat soko pull --id 123456\nnpx hardhat soko pull --tag v1.2.3\nnpx hardhat soko pull --tag v4.5.6 --project another-project\n```\n\n### Typings\n\nOnce the artifacts have been pulled, one can generate the TypeScript typings based on the pulled projects.\n\n```bash\nnpx hardhat soko typings\n```\n\n\u003e [!NOTE]\n\u003e If no projects have been pulled, one can still generate the default typings using this command. It may be helpful for those who do not care about the scripts involving Soko but want to be unblocked in case of missing files.\n\n### List\n\nList the pulled projects and their compilation artifacts.\n\n```bash\nnpx hardhat soko list\n```\n\n### Diff\n\nCompare a local compilation artifacts with an existing compilation artifact and print the contracts for which differences have been found.\n\n```bash\nnpx hardhat soko diff --artifact-path ./path/to/my/artifact.json --tag v1.2.3\nnpx hardhat soko diff --artifact-path ./path/to/my/artifact.json --id 123456\n```\n\n## Using the typings\n\nThe typings are exposed in order to help the developer retrieve easily and safely a contract artifact (ABI, bytecode, etc...).\n\nThere are two available utils in order to retrieve a contract artifact, it would depend on the task at hand:\n\n- start with a contract, select one of its available tag\n\n```ts\nimport { project } from \"../.soko-typings\";\n\nconst artifact = await project(\"my-project\")\n  .contract(\"src/path/to/my/contract.sol:MyExampleContract\")\n  .getArtifact(\"v1.2.3\");\n```\n\n- start with a tag, select a contract within it\n\n```ts\nimport { project } from \"../.soko-typings\";\n\nconst artifact = await project(\"my-project\")\n  .tag(\"v1.2.3\")\n  .getContractArtifact(\"src/path/to/my/contract.sol:MyExampleContract\");\n```\n\nIf typings have been generated from existing projects, the inputs of the utils will be strongly typed and wrong project, tags or contracts names will be detected.\n\nIn case there are no projects or the projects have not been pulled, the generated typings are made in such a way that strong typecheck disappears and any string can be used with the helper functions.\n\n### Retrieve full compilation artifact\n\nThe full compilation artifact of a tag can be retrieved using the `project(\"my-project\").tag(\"v1.2.3\").getCompilationArtifact` method.\n\n### Example with hardhat-deploy\n\nAn example can be made with the [hardhat-deploy](https://github.com/wighawag/hardhat-deploy) plugin for deploying a released smart contract.\n\nThe advantage of this deployment is that it only works with frozen artifacts. New development will never have an impact on it.\n\n```ts\nimport { HardhatRuntimeEnvironment } from \"hardhat/types\";\nimport { DeployFunction } from \"hardhat-deploy/types\";\nimport { project } from \"../.soko-typings\";\n\nconst deployMyExample: DeployFunction = async function (\n  hre: HardhatRuntimeEnvironment,\n) {\n  const { deployer } = await hre.getNamedAccounts();\n\n  const myExampleArtifact = await project(\"my-project\")\n    .contract(\"src/Example.sol:MyExample\")\n    .getArtifact(\"v1.2.3\");\n\n  await hre.deployments.deploy(`MyExample@v1.2.3`, {\n    contract: {\n      abi: myExampleArtifact.abi,\n      bytecode: myExampleArtifact.evm.bytecode.object,\n      metadata: myExampleArtifact.metadata,\n    },\n    from: deployer,\n  });\n};\n\nexport default deployMyExample;\n```\n\n## Integration examples\n\nHere are examples of integration with Hardhat Soko in order to handle the releases of smart contracts, deployments and publication of NPM packages containing ABI and deployment addresses:\n\n- [everything with Hardhat](https://github.com/VGLoic/hardhat-soko-example),\n- [compilation and testing with Foundry, deployments with Hardhat](https://github.com/VGLoic/foundry-hardhat-soko-example).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvgloic%2Fhardhat-soko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvgloic%2Fhardhat-soko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvgloic%2Fhardhat-soko/lists"}