feat: compact-deployer tool (#86)

* feat(deployer): add compact-deployer tool and CLI deploy command

Introduce the `@openzeppelin/compact-deployer` package: a programmatic
and CLI deployer for Compact contracts. Covers config loading, artifact
and constructor-arg resolution, wallet/keystore handling, network and
proof-server providers, and deployment-record bookkeeping.

Wire the deployer into `@openzeppelin/compact-cli` via the new
`compact-deploy` command (runDeploy), with passphrase prompting and
JSON/verbose output modes.

* Add root resolutions for the midnight stack and a `coverage` turbo
  task so the new package can report coverage.

Part 1 of 2 splitting the original deployer PR. Examples and the
integration-test suite follow in a stacked PR that builds on this one.

Refs: #86

* fix(deployer): address CodeRabbit review feedback

Harden the deployer tool and CLI against the issues raised in the #86
review. Each fix verified against current code and covered by tests.

* cli/logger: route `--json` pino logs to STDERR (fd 2) so STDOUT
  carries only the single result object.
* cli/prompt: write the passphrase prompt + newline to STDERR, and
  settle the promise on stdin `end`/`error` so non-interactive input
  (closed/newline-less pipe) can no longer hang the CLI.
* config/schema: mark the file/module ref union members `.strict()`
  so an ambiguous `{ file, module }` is rejected instead of silently
  dropping a key.
* deployments: write the ledger atomically (temp file + rename) so a
  crash mid-write can't truncate `*.json`.
* loaders/artifact: bind compiled assets to `dirname(entry)` rather
  than a hardcoded `contract/`, fixing the top-level-`index.js` case.
* loaders/constructor-meta: allow an empty named-args object for a
  no-arg constructor (resolves to `[]`); `reorderNamedArgs` still
  rejects unexpected keys.
* loaders/contract-resolve: use `path.isAbsolute` instead of
  `startsWith('/')` for OS-correct absolute-path detection.
* providers/network: drop `mainnet` from the allow-list while the
  deployer is testnet/preview-only.
* providers/proof-server: reject partial-numeric and out-of-range
  `PROOF_SERVER_PORT` values (full `\d+` match + 1..65535 bounds).
* wallet/handler: use `path.dirname`/`basename` instead of manual
  `/` splitting so cache paths work on Windows.
* wallet/keystore: validate shape in `fromJSON` and throw `WalletError`
  (not a raw `TypeError`) on malformed keystore JSON.

Refs: #86

* fix(deployer): unblock preprod wallet sync

preprod's dust history is a ~1M-event global stream that every client
replays on sync. Deploying any contract there failed before a tx was
ever built: the dust wallet OOMed mid-replay, and once that was worked
around the sync gate never completed. Both trace to the pre-fix
wallet-sdk-dust-wallet@4.0.0 pin (midnightntwrk/midnight-wallet#425).

* wallet/handler: set batchUpdates = { size: 5000, timeout: 1,
  spacing: 4 } on the shared wallet config so the fresh-sync and the
  cache-restore paths (shielded + dust alike) stream the replay in
  larger chunks instead of exhausting the V8 heap at the SDK default
  batch size of 10.
* deployer: replace the strict FacadeState.isSynced tip gate with
  isCompleteWithin(50) on each sub-wallet. On a live chain the dust
  stream advances continuously, so strict completion never fires and
  the gate timed out on a fully usable wallet. The gate still waits on
  all three sub-wallets to avoid the custom-error-170 regression.
* cli + README: document the NODE_OPTIONS max-old-space-size bump
  still useful for a first preprod sync, plus the tolerant tip gate.

Verified on preprod: ShieldedFungibleToken dry-run synced to tip in
~1m12s from a warm cache (dust ~1.08M events, no OOM) and the gate
completed even though dust never reached strict completion.

Closes #115

* feat(deployer): make sync batch size configurable

The dust/shielded sync batch size was hard-coded to 5000 (the #115 OOM
workaround). Expose it as a knob so operators can trade memory against
replay speed without recompiling, while keeping 5000 as the default.

* wallet/handler: add `syncBatchSize` to WalletHandlerBuildOptions;
  fall back to DEFAULT_SYNC_BATCH_SIZE (5000). timeout/spacing stay at
  the validated values.
* deployer: thread `syncBatchSize` from DeployerOptions through to the
  owned-wallet build (ignored when a wallet is injected).
* cli: add `--sync-batch-size <n>` (positive-integer validated, mirrors
  --sync-timeout) and document it in --help and the README.

Refs: #115

* feat(deployer): allow sync knobs in compact.toml

The sync batch size and sync timeout were CLI/programmatic only, so an
operator had to pass `--sync-batch-size` / `--sync-timeout` on every run
for a long-history network like preprod. Let them live in config too.

* config/schema: add optional `sync_timeout` (seconds) and
  `sync_batch_size` to `[networks.X]`, both positive integers.
* deployer: resolve each with precedence CLI/programmatic option >
  TOML network value > built-in default (10 min / 5000). Applies only
  to the owned-wallet build; ignored when a wallet is injected.
* README: document the keys, the precedence, and a preprod example.

Refs: #115

* docs(deployer): document npx + local-install for the CLI

Add an "Install & run" section: the `compact-deploy` bin ships in
@openzeppelin/compact-cli, and `npx compact-deploy` resolves the local
install so the deployer and the compiled contracts share one
compact-runtime copy (required for a real deploy). Note that fully
ephemeral `npx @openzeppelin/compact-cli …` is fine for help/dry-run but
not for real deploys, since its cache-tree runtime differs from the
project's and the submit fails the ContractMaintenanceAuthority check.

Refs: #115

* fix(deployer): apply review fixes and drop the barrel

Secret handling, dead dependency pruning, keystore hardening, and the
--version flag, from the review of PR #86.

Replaces src/index.ts with explicit package.json subpath exports. Each
module is now reached by its own path, so the noBarrelFile suppression
is gone and consumers no longer pull the whole package to import one
symbol. Internals stay unexported.

* refactor(deployer): split services out and cache the unshielded wallet

Extracts five single-responsibility modules under src/services/:
file-lock, atomic-json, wallet-sync, wallet-cache, and deploy-tx. They
stay internal, with no package.json subpath, so the public surface is
unchanged. deployments.ts, deployer.ts, and wallet/handler.ts shed the
locking, syncing, persistence, and tx-submission code they had absorbed.

Caches the unshielded sub-wallet alongside shielded and dust, with a
matching --seed-cache-from-unshielded flag. The sync gate already waited
on unshielded progress, so an uncached one re-synced from genesis and
dominated every warm boot.

Narrows two swallowed errors in file-lock. A stale-break fault that is
not ENOENT now surfaces instead of retrying into a misleading lock
timeout, and a failed release warns rather than vanishing. Release still
never throws: it runs in the caller's finally, where throwing would mask
a real error or fail an already-successful deploy.

Coverage thresholds move to 100 in all four metrics, which the package
now meets.

* fix(deployer): address CodeRabbit review on PR 86

Catch a rejected onCheckpoint in syncAndVerifyFunds. The callback ran as
`onCheckpoint().finally(...)`, so a rejection was never consumed and Node
would terminate the process, contradicting the documented best-effort
contract of the surrounding comment.

Reject a keystore dklen other than 32 in encrypt. The value reached
scryptSync directly, and a shorter derived key left an empty MAC key,
so encrypt would write a keystore that its own schema then refuses to
read back.

Fix the default_network test fixture. It appended a second [profile]
table, which smol-toml rejects as a redefinition, so the test passed on
the TOML parse error and never reached the validation branch it names.
Covering that branch properly left the invalid-TOML path untested, so it
gets its own case.

Document compact-deploy in the CLI README, which listed only the compiler
and builder binaries while requiring Node 24 for a deployer it never
mentioned. Correct the deployer README's real-network guidance, which
pointed at preview while its own known-issues section records preview as
null-routed.

* build(deployer): move to the ledger-v8 8.1 stack

ledger-v8 8.1.2, midnight-js and testkit-js 4.1.1, wallet-sdk-facade
4.0.1 with dust-wallet 4.1.0, shielded 3.0.1, unshielded 3.1.0 and
address-format 3.1.2. compact-runtime stays on 0.16.0. compact-js stays
on 2.5.1: 2.5.3 depends on an unpublished ledger-v9 alpha.

The five wallet-sdk root resolutions are load-bearing. testkit-js pulls
wallet-sdk 1.1.0, whose ^4.0.1 facade range resolves to 4.1.0, and that
version imports a nonexistent Clock export and fails to load. No
resolution is set for midnight-js-protocol: the 4.1.1 packages pin it
exactly, and a global pin would downgrade the simulator's 5.0.0-beta.7
tree.

* fix(deployer): keep state under the config dir

The wallet-state cache and the LevelDB private-state store resolved
against process.cwd(), so a deploy run from any other directory
re-synced from genesis and started from an empty private state. Both
now hang off the compact.toml directory. rootDir is a required option
on WalletHandler, WalletCache and buildProviders so a silent CWD
default cannot come back. --seed-cache-from-* paths stay CWD-relative
because the user typed them at the shell.

Wallet-SDK rejections are effect-style tagged records, not Errors, so
the warn sites logged "[object Object]". formatError renders _tag and
message instead.

README: record the 2026-09-04 preprod dry run on this stack (synced to
tip, the old deserialize failure did not reproduce) and why the
wallet-sdk resolutions must survive dependency bumps.

* fix(deployer): format tagged SDK errors on exit paths

formatError was wired into the warn-and-continue sites only. A tagged
wallet-SDK rejection escaping the sync or the deploy call still hit
`(e as Error).message` and printed "[DEPLOY] undefined". The CLI catch,
the deploy wrapper and the proof-server dispose now go through it, so
the module gains a package export for the CLI.

The fallbacks also lose less: an Error appends its cause chain, and
util.inspect replaces the hand-rolled JSON serializer, rendering bigint
and marking circular references instead of degrading to
"[object Object]".

* refactor(deployer): drop SDK casts, dedupe rootDir doc

The restore casts in wallet-cache were redundant: the wallet-SDK factory
and DustWallet.restore already return types assignable to
ShieldedWalletAPI and DustWalletAPI. describeProgress cast its input to
a loose shape; it now takes a union of the two sub-wallet progress
shapes, mirrored structurally because neither SDK type reaches a package
root the deployer depends on. Test fixtures gained the counters the
real SDK always populates, so the `?? 0n` props are gone.

The rootDir explanation lived on three option types; it now lives once
on CompactConfig.rootDir with one-line pointers elsewhere.

* docs(deployer): state the LevelDB lock scope

Both the wallet cache and the LevelDB store now hang off the
compact.toml directory, so the project is the unit of state and a
second concurrent compact-deploy in the same project fails on the
LevelDB lock.

* build(deployer): drop unused axios and testcontainers

Neither is imported anywhere under packages/deployer/src. The only
container use goes through @midnight-ntwrk/testkit-js, which brings its
own testcontainers 12; the direct ^10 pin added a second copy with a
second dockerode major.

* ci(release): wire compact-deployer into the release flow

compact-cli depends on @openzeppelin/compact-deployer via workspace:^,
which yarn rewrites to a concrete version at pack time, but neither
release workflow knew the package, so a cli release after merge would
point at an npm version nothing can publish. The deployer joins the
workflow choice lists, gets its repository field, and moves ahead of
the cli in the first-release order.

RELEASING.md requires a CHANGELOG.md per published package. Both new
files start with an Unreleased section; the cli entry records the Node
24 floor as Breaking, since compact-deploy relies on explicit resource
management (await using, AsyncDisposableStack) that Node 22 lacks and
the bump lands on compact-compiler and compact-builder users too. The
changelogs are added to the files arrays so they ship in the tarballs.

* docs(deployer): state the supported Midnight stack

The deployer pins compact-runtime 0.16.0 and ledger-v8, and needs
artifacts from compactc 0.31.1; the default 0.34 compiler targets
runtime 0.19.0 and the deploy fails with a version mismatch. The
README now says so up front, notes that compact-contracts main (runtime
0.19.0, ledger-v9) is not deployable with this tool yet, and names the
blocker: compact-js 2.5.3 depends on an unpublished ledger-v9 alpha.
The root README gains the deployer package and corrects the Node
requirements per package.

* docs(deployer): library callers must inject the private-state provider

The default LevelDB store is opened per deploy and holds its lock until
the process exits, so a script that deploys several contracts in one
process needs privateStateProvider next to walletProvider.

* chore: gitignore compact-deploy verbose logs

* fix(deployer): resolve --seed-file against the CWD

--config and --seed-cache-from-* already resolve against the shell CWD;
--seed-file alone resolved against the compact.toml directory, so a
relative path typed from a subdirectory read the wrong file. A relative
[wallet].keystore keeps the rootDir anchor because it comes from the
config file, not the shell.

* fix(deployer): reject scrypt params the KDF itself refuses

The schema bounded n and r separately, but scryptSync also enforces a
memory budget and an n < 2^(16r) ceiling, so a keystore with n=2^20 r=8
passed validation and then surfaced as a raw OpenSSL RangeError. One
predicate now models both limits and runs in the schema and in encrypt.

fromJSON also lost its hand-written pre-checks: they restated what the
zod schema already enforces, and the schema error names the field.

* fix(deployer): type the wallet sync timeout as WalletError

A bare Error exited 1; errors.ts promises a stable code per failure
mode, and a sync timeout is a wallet failure (exit 3).

* fix(deployer): break stale locks without a double acquire

Two waiters that both saw a stale lock could each unlink it: the first
re-created the lock, the second removed that fresh file and acquired
alongside the holder. The break now renames the lock aside (atomic, one
winner), re-checks the parked file's age, and restores it if a waiter
had already taken over. The lock timeout is a DeployError instead of a
bare Error.

* refactor(deployer): drop the unreachable mainnet fee branch

applyNetwork rejects mainnet, so the additionalFeeOverhead fallback to
the testkit default could never run.

* fix(deployer): load args and init state before the wallet sync

Both depend only on the config and the artifact, and a typo in either
used to surface after a 30-60 min first preprod sync.

* fix(deployer): format tagged SDK rejections in runDeploy

The library entrypoint still rendered a wallet-SDK tagged record as
"[object Object]"; 298def0 fixed the CLI arm only.

* fix(deployer): record the deploy before waiting for finalization

deployContract fuses submission and the wait for finalization and yields
no identifier until the tx has landed, so a WebSocket drop or indexer
stall left the CLI spinning with nothing to reconcile, and any failure
in that window reported a deploy that may already be on chain as
failed. The three SDK steps now run explicitly: createUnprovenDeployTx,
submitTxAsync, then watchForTxData raced against --tx-timeout (default
600 s), with the private-state and signing-key writes only after a
SucceedEntirely status.

The deployments ledger gains a pending state. A record with the address
and txId is written as soon as the node accepts the tx and promoted to
confirmed on finalization. A timeout or rejection leaves it pending and
names both identifiers in the error; the next deploy of that contract
refuses until --force, and the check runs before proving so a blocked
deploy costs no fees.

Every ledger write is logged at info first and a failing write (lock
timeout, EACCES, malformed <network>.json) rethrows as
DeploymentsFileError, exit 6, carrying address, txId and txHash.
readJson wraps a SyntaxError with the file path instead of leaking it.

IndexerUnreachableError and ProofServerUnreachableError had no call
site and are gone; exit code 4 is unused.

* test(deployer): cover the untagged-record message fallback

* build(cli): drop the ws WebSocket shim

Node 24 ships a native global WebSocket and midnight-js reads that
global rather than importing ws. Verified on a local node: with the
native class pinned, sync, deploy and watchForTxData all completed;
with WebSocket forced to undefined the sync never connected. The shim
and the ws / @types/ws dependencies go; ws stays in the lockfile only
as a transitive dependency of the indexer provider and testkit-js.

* fix(deployer): silence the testkit-js module logger

testkit-js builds a pino logger at import and pretty-prints through it
to stdout, ignoring the logger passed into every call, so
`compact-deploy --json | jq` failed on an "Initializing wallet builder"
line that landed before the result object. The logger is exported;
setting its level to silent at module load stops the line. The empty
`<cwd>/logs/tests/` file the same logger creates on import cannot be
prevented from user code and needs an upstream change.

* fix(deployer): surface the cause behind Effect failures

With the proof server down the CLI printed only "Failed to prove
transaction". The wallet SDK does attach the connection error as the
cause, but Effect.runPromise rejects with a FiberFailure that copies the
message and leaves `cause` unset; the real failure hangs off the
registered symbol effect/Runtime/FiberFailure/Cause. formatError now
unwraps that symbol (no runtime dependency on effect) and collapses a
wrapper whose cause repeats its message, so the line reads
"Failed to prove transaction: Failed to connect to Proof Server:
Transport error (POST http://127.0.0.1:6300/prove): fetch failed".

Author: 0xisk

.github/workflows/release-publish.yml

@@ -18,6 +18,7 @@ on:
         options:
           - compact-builder
           - compact-cli
+          - compact-deployer
           - compact-simulator
 
 jobs:
@@ -67,6 +68,7 @@ jobs:
             case "$PKG" in
               compact-builder)   DIR="builder" ;;
               compact-cli)       DIR="cli" ;;
+              compact-deployer)  DIR="deployer" ;;
               compact-simulator) DIR="simulator" ;;
               *)
                 echo "::error::unknown package: $PKG"
@@ -85,6 +87,7 @@ jobs:
             case "$DIR" in
               builder)   PKG="compact-builder" ;;
               cli)       PKG="compact-cli" ;;
+              deployer)  PKG="compact-deployer" ;;
               simulator) PKG="compact-simulator" ;;
               *)
                 echo "::error::unknown package directory: $DIR"

.github/workflows/release.yml

@@ -10,6 +10,7 @@ on:
         options:
           - compact-builder
           - compact-cli
+          - compact-deployer
           - compact-simulator
       version_bump:
         description: "Version bump type (pre* strategies are beta-only)"
@@ -85,6 +86,9 @@ jobs:
             "compact-cli")
               echo "dir=cli" >> $GITHUB_OUTPUT
               ;;
+            "compact-deployer")
+              echo "dir=deployer" >> $GITHUB_OUTPUT
+              ;;
             "compact-simulator")
               echo "dir=simulator" >> $GITHUB_OUTPUT
               ;;

.gitignore

@@ -5,12 +5,19 @@
 *.local
 package-lock.json
 .pnp.*
+**/.pnp.*
 .yarn/*
 !.yarn/patches
 !.yarn/plugins
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+# Nested yarn state (e.g. `examples/<name>/.yarn/cache`) shouldn't ship.
+# Examples install standalone; their cache regenerates from yarn.lock.
+**/.yarn/cache
+**/.yarn/install-state.gz
+**/.yarn/build-state.yml
+**/.yarn/unplugged
 
 logs
 log
@@ -22,10 +29,38 @@ result
 dist/
 gen/
 managed/
+# Compiler output. Regenerated by `compact-compiler` on every build, so it
+# never gets committed — including under examples/, where the walkthrough
+# expects you to compile the contract yourself before deploying.
 artifacts/
 midnight-level-db
 compactc
 
+# Deploy secrets — wallet seeds, signing keys, keystores. Match at any depth
+# so nested deploy/ directories (e.g. under examples/) are covered too.
+**/deploy/*.seed
+**/deploy/*.signingkey
+**/deploy/*.keystore.json
+
+# Deployment records — the JSON the deployer writes after a successful
+# deploy. Includes the contract signing key, so treat as a secret.
+deployments/
+
+# compact-deployer wallet-state cache (per-seed, per-network shielded snapshots).
+.states/
+**/.states/
+
+# compact-deployer run logs, written by `compact-deploy --verbose`.
+.compact/
+**/.compact/
+
+# Third-party source pulled in for local experimentation (e.g. the
+# midnight-node fork validation under vendor/midnight-node/ — see
+# plans/tooling/compact-deploy-rust-fork.md). Never committed.
+vendor/
+target/
+.toolkit-cache/
+
 coverage
 **/reports
 

README.md

@@ -15,10 +15,11 @@ This project extends the Midnight Network with additional developer tooling.
 > risk. See [SECURITY.md](./SECURITY.md) for the full disclaimer and for how
 > to report a vulnerability.
 
-Tools for compiling, building, and testing Compact smart contracts. This is a monorepo containing:
+Tools for compiling, building, testing, and deploying Compact smart contracts. This is a monorepo containing:
 
 - [`packages/builder`](./packages/builder) — programmatic library that drives the Compact compiler + builder
-- [`packages/cli`](./packages/cli) — thin bin wrapper around the builder library (`compact-compiler`, `compact-builder`)
+- [`packages/cli`](./packages/cli) — thin bin wrapper around the builder and deployer libraries (`compact-compiler`, `compact-builder`, `compact-deploy`)
+- [`packages/deployer`](./packages/deployer) — deployer library that submits a compiled contract to a Midnight network. Pins one Midnight stack: see [Supported stack](./packages/deployer/README.md#supported-stack)
 - [`packages/simulator`](./packages/simulator) — TypeScript simulator to run and test Compact contracts locally
 
 See each package's README for usage, options, and examples.
@@ -36,14 +37,19 @@ yarn add --dev @openzeppelin/compact-cli
 
 # Simulator — test Compact contracts locally
 yarn add --dev @openzeppelin/compact-simulator
+
+# Deployer — deploy a compiled contract from TypeScript
+yarn add --dev @openzeppelin/compact-deployer
 ```
 
-`compact-cli` depends transitively on `compact-builder`, so installing the CLI
-gives you both the binaries and the underlying library.
+`compact-cli` depends transitively on `compact-builder` and
+`compact-deployer`, so installing the CLI gives you both the binaries and the
+underlying libraries.
 
 ```bash
 yarn compact-compiler --help
 yarn compact-builder --help
+yarn compact-deploy --help
 ```
 
 ```ts
@@ -53,7 +59,7 @@ import { createSimulator } from '@openzeppelin/compact-simulator';
 
 ## Requirements
 
-- Node.js >= 20 (root and `packages/cli`), >= 22 for `packages/simulator`
+- Node.js >= 22 for `packages/builder` and `packages/simulator`, >= 24 for `packages/cli` and `packages/deployer`
 - Yarn 4 (Berry)
 - Turbo
 - Optional: Midnight Compact toolchain installed and available in `PATH`

RELEASING.md

@@ -80,23 +80,26 @@ breaking change. After that, only `prerelease` moves the counter. Running
 
 ## First-release order
 
-There's a one-step dependency chain across the three published packages:
+There's a one-step dependency chain across the four published packages:
 
 ```text
 compact-cli (bin wrapper)
-  └─ depends on compact-builder
+  ├─ depends on compact-builder
+  └─ depends on compact-deployer
 compact-builder (library)
+compact-deployer (library)
 compact-simulator (library)
 ```
 
-The `workspace:^` dep is rewritten by yarn into the resolved version at
+The `workspace:^` deps are rewritten by yarn into the resolved versions at
 `yarn pack` time. For the very first release, publish in dependency order so
 each dependent finds its deps already on npm:
 
 1. `compact-builder` (no internal deps)
 2. `compact-simulator` (no internal deps)
-3. `compact-cli` (depends on `compact-builder`; pull `main` first so the bump
-   commit is present locally before triggering)
+3. `compact-deployer` (no internal deps)
+4. `compact-cli` (depends on `compact-builder` and `compact-deployer`; pull
+   `main` first so both bump commits are present locally before triggering)
 
-After the first release, the three packages version independently — bump any
+After the first release, the four packages version independently — bump any
 one of them in isolation without re-publishing the others.

package.json

@@ -9,6 +9,7 @@
   "scripts": {
     "build": "turbo run build --log-prefix=none",
     "test": "turbo run test --log-prefix=none",
+    "coverage": "turbo run coverage --log-prefix=none",
     "lint": "biome check .",
     "lint:fix": "biome check . --write",
     "lint:ci": "biome ci . --no-errors-on-unmatched",
@@ -17,10 +18,24 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.6",
+    "@openzeppelin/compact-deployer": "workspace:^",
     "@types/node": "26.1.2",
+    "@vitest/coverage-v8": "4.1.9",
+    "pino": "^9.7.0",
     "ts-node": "^10.9.2",
     "turbo": "^2.10.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
+  },
+  "resolutions": {
+    "@midnight-ntwrk/ledger-v8": "8.1.2",
+    "@midnight-ntwrk/wallet-sdk-address-format": "3.1.2",
+    "@midnight-ntwrk/wallet-sdk-dust-wallet": "4.1.0",
+    "@midnight-ntwrk/wallet-sdk-facade": "4.0.1",
+    "@midnight-ntwrk/wallet-sdk-shielded": "3.0.1",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "3.1.0",
+    "undici": "^6.24.0",
+    "glob": "^11.0.0",
+    "uuid": "^13.0.0"
   }
 }

packages/cli/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@openzeppelin/compact-cli` are documented in this
+file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Releases before this file see the `compact-cli/v*` tags.
+
+## Unreleased
+
+### Added
+
+- `compact-deploy` bin, a wrapper around [`@openzeppelin/compact-deployer`](../deployer) that deploys a compiled contract to a Midnight network (#86)
+
+### Changed
+
+- **Breaking:** compact-cli now requires Node 24. compact-deploy uses explicit resource management (`await using`, `AsyncDisposableStack`), unavailable on Node 22. (#86)

packages/cli/README.md

@@ -1,9 +1,11 @@
 # @openzeppelin/compact-cli
 
-CLI wrapper around [`@openzeppelin/compact-builder`](../builder).
-Provides the `compact-compiler` and `compact-builder` binaries for use in
-`package.json` scripts. Contains no programmatic API of its own. If you want
-to call the compiler/builder from TypeScript, use the library package directly.
+CLI wrapper around [`@openzeppelin/compact-builder`](../builder) and
+[`@openzeppelin/compact-deployer`](../deployer). Provides the
+`compact-compiler`, `compact-builder`, and `compact-deploy` binaries for use
+in `package.json` scripts. Contains no programmatic API of its own. If you
+want to call the compiler, builder, or deployer from TypeScript, use the
+library package directly.
 
 ## Install
 
@@ -16,6 +18,7 @@ yarn add --dev @openzeppelin/compact-cli
 ```bash
 yarn compact-compiler --help
 yarn compact-builder --help
+yarn compact-deploy --help
 ```
 
 Typical `package.json` scripts (replace `<version>` with the Compact
@@ -34,9 +37,20 @@ toolchain release you want to pin, e.g. `+0.29.0`):
 
 ## Options
 
-Both binaries accept the same compiler-side options (forwarded to the
-underlying library); `compact-builder` additionally accepts dist-layout
-options:
+### `compact-deploy`
+
+Deploys a compiled contract to a Midnight network. Options are documented
+in full under [`@openzeppelin/compact-deployer`](../deployer); the common
+ones are `--network`, `--config`, `--seed-file`, `--dry-run`, and `--json`.
+
+```bash
+compact-deploy <Contract> --network local
+```
+
+### `compact-compiler` and `compact-builder`
+
+Both accept the same compiler-side options (forwarded to the underlying
+library); `compact-builder` additionally accepts dist-layout options:
 
 | Flag | Applies to | Description |
 |---|---|---|
@@ -55,7 +69,7 @@ documentation, programmatic API, and behavioural details.
 
 ## Requirements
 
-- Node.js >= 20
+- Node.js >= 24 for `compact-deploy`, which uses explicit resource management (`await using` / `AsyncDisposableStack`), global only from Node 24. The compiler and builder binaries run on older releases.
 - Midnight Compact toolchain installed and available in `PATH`
 
 ```bash

packages/cli/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@openzeppelin/compact-cli",
-  "description": "CLI for compiling and building Compact smart contracts",
+  "description": "CLI for compiling, building, and deploying Compact smart contracts",
   "version": "0.0.3",
   "keywords": [
     "compact",
     "cli",
     "compiler",
     "builder",
+    "deployer",
     "testing"
   ],
   "author": "OpenZeppelin Community <maintainers@openzeppelin.org>",
@@ -19,24 +20,28 @@
   "type": "module",
   "exports": {
     "./run-builder": "./dist/runBuilder.js",
-    "./run-compiler": "./dist/runCompiler.js"
+    "./run-compiler": "./dist/runCompiler.js",
+    "./run-deploy": "./dist/runDeploy.js"
   },
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "bin": {
     "compact-builder": "dist/runBuilder.js",
-    "compact-compiler": "dist/runCompiler.js"
+    "compact-compiler": "dist/runCompiler.js",
+    "compact-deploy": "dist/runDeploy.js"
   },
   "scripts": {
     "build": "tsc -p .",
     "types": "tsc -p tsconfig.json --noEmit",
     "test": "yarn vitest run",
+    "coverage": "yarn vitest run --coverage",
     "clean": "git clean -fXd"
   },
   "devDependencies": {
@@ -47,7 +52,10 @@
   },
   "dependencies": {
     "@openzeppelin/compact-builder": "workspace:^",
+    "@openzeppelin/compact-deployer": "workspace:^",
     "chalk": "^6.0.0",
-    "ora": "^9.4.1"
+    "ora": "^9.4.1",
+    "pino": "^9.7.0",
+    "pino-pretty": "^13.0.0"
   }
 }