deployment-remote-source-integrity

name	deployment-remote-source-integrity
description	Use before deploying the bridge, deploying a DApp, registering a DApp, or uploading bridge/DApp deployment metadata from this repository. It enforces that deployment metadata can point users to source code that already exists on the remote repository.

Deployment Remote Source Integrity

Use this skill before any operation that deploys the bridge, deploys a DApp, registers a DApp, or uploads bridge.*.json or deployment.*.*.json metadata.

Entry Scripts

Use these repository entrypoints for deployment and registration work:

• Bridge deployment: node bridge/scripts/deploy-bridge.mjs ...
• Private-state DApp deployment: node packages/apps/private-state/scripts/deploy/deploy-private-state.mjs ...
• Private-state DApp deployment artifact writing: node packages/apps/private-state/scripts/deploy/write-deploy-artifacts.mjs <chain-id>
• DApp registration: node bridge/scripts/admin-add-dapp.mjs ...
• Combined private-state DApp deploy-and-register wrapper: node bridge/scripts/deploy-and-add-dapp.mjs ...

The combined wrapper does not bypass any of this skill's checks. Apply the bridge/DApp deployment and DApp registration checks before running it.

External NPM Dependencies

Before running any entry script, upgrade its external npm dependencies from the npm registry. Do not use npm ci, and do not rely on package-lock.json to choose dependency versions. Use npm install --no-save --package-lock=false <package>@latest ... so the deployment uses registry latest without rewriting package manifests or lockfiles.

Entry script dependency sets:

• bridge/scripts/deploy-bridge.mjs
  • @ethereumjs/util
  • @tokamak-private-dapps/common-library
  • @tokamak-private-dapps/groth16
  • @tokamak-zk-evm/cli
  • @tokamak-zk-evm/subcircuit-library
  • @tokamak-zk-evm/synthesizer-node
  • @google-cloud/local-auth
  • dotenv
  • ethers
  • googleapis
  • yauzl
  • yazl
• packages/apps/private-state/scripts/deploy/deploy-private-state.mjs
  • @tokamak-private-dapps/common-library
  • dotenv
• packages/apps/private-state/scripts/deploy/write-deploy-artifacts.mjs
  • no external npm dependency beyond the repository-local helpers and the forge executable
• bridge/scripts/admin-add-dapp.mjs
  • @tokamak-private-dapps/common-library
  • @tokamak-zk-evm/cli
  • @tokamak-zk-evm/subcircuit-library
  • @tokamak-zk-evm/synthesizer-node
  • @google-cloud/local-auth
  • ethers
  • googleapis
• bridge/scripts/deploy-and-add-dapp.mjs
  • union of the private-state DApp deploy dependencies and DApp registration dependencies

For a bridge deployment, run:

npm install --no-save --package-lock=false \
  @ethereumjs/util@latest \
  @tokamak-private-dapps/common-library@latest \
  @tokamak-private-dapps/groth16@latest \
  @tokamak-zk-evm/cli@latest \
  @tokamak-zk-evm/subcircuit-library@latest \
  @tokamak-zk-evm/synthesizer-node@latest \
  @google-cloud/local-auth@latest \
  dotenv@latest \
  ethers@latest \
  googleapis@latest \
  yauzl@latest \
  yazl@latest

For a private-state DApp deployment, run:

npm install --no-save --package-lock=false \
  @tokamak-private-dapps/common-library@latest \
  dotenv@latest

For a DApp registration, run:

npm install --no-save --package-lock=false \
  @tokamak-private-dapps/common-library@latest \
  @tokamak-zk-evm/cli@latest \
  @tokamak-zk-evm/subcircuit-library@latest \
  @tokamak-zk-evm/synthesizer-node@latest \
  @google-cloud/local-auth@latest \
  ethers@latest \
  googleapis@latest

Bridge Deployment Mode

Bridge deployment supports upgrade and redeploy-proxy modes through node bridge/scripts/deploy-bridge.mjs --mode <mode>.

• Sepolia: prefer upgrade only when an existing proxy deployment artifact is usable and storage layout compatibility between the previous implementation and the current implementation is guaranteed for every proxy being upgraded. Use redeploy-proxy when there is no usable proxy deployment artifact, when storage layout compatibility is not guaranteed, or when the user explicitly requests a forced proxy redeployment.
• Mainnet: if a bridge proxy is already deployed, use upgrade mode only. Do not run redeploy-proxy against mainnet once a proxy exists, even if the user request is informal or ambiguous. Stop and ask for clarification if the available metadata does not make proxy existence clear.

Hard Rule

Do not deploy or register unless the exact local HEAD commit is already present on the remote main branch of the repository that will be written into deployment metadata.

If the check fails, stop before deployment and tell the user to push the commit first. Do not infer permission to push unless the user explicitly requested it.

Required Remote Main Check

Run this immediately before the deployment or registration command:

git fetch --prune origin main
head_sha="$(git rev-parse HEAD)"
git merge-base --is-ancestor "$head_sha" origin/main

The check passes only if origin/main contains HEAD. A tag or another remote branch is not enough. If this command fails, the commit is not present on remote main and deployment must stop.

Contract Code Diff Check

Before bridge deployment or DApp deployment, compare the current execution commit with the commit recorded in the latest existing deployment metadata:

• Bridge deployment metadata: latest bridge.*.json for the target chain.
• DApp deployment metadata: latest deployment.*.*.json for the target app and chain.
• Previous commit field: .sourceCode.repository.commit.
• Current commit: git rev-parse HEAD.

If the previous deployment metadata has no source commit, or the previous commit cannot be fetched or resolved locally, stop and ask the user before deployment unless they explicitly requested a forced deployment.

For the diff, compare deployment-relevant Solidity contract sources only:

• Bridge: bridge/src/**/*.sol
• Private-state DApp: packages/apps/private-state/src/**/*.sol

Use a command equivalent to:

git fetch --prune origin main
previous_sha="<commit from latest deployment metadata>"
current_sha="$(git rev-parse HEAD)"
git diff --name-only "$previous_sha" "$current_sha" -- ':(glob)bridge/src/**/*.sol'
git diff --name-only "$previous_sha" "$current_sha" -- ':(glob)packages/apps/private-state/src/**/*.sol'

Apply the bridge path for bridge deployment and the DApp path for DApp deployment. If the relevant diff is empty, refuse to deploy because there is no substantive contract-code change. Proceed only when the user explicitly requested a forced deployment in the current task.

DApp registration alone does not require this contract-code diff check unless it also runs a DApp deployment through the combined wrapper.

Dirty Worktree

If deployment-relevant source, generated verifier code, deployment scripts, metadata helpers, or artifact upload scripts are modified in the working tree, do not deploy from that dirty state. Commit those changes first, then apply the remote-presence check above.

Branch Labels

Deployment metadata may record branch labels such as a normal branch name, tagged, detached head, CI, or unknown. These labels do not replace the remote-presence check. The commit hash is the source-of-truth for whether sourceUrl can resolve.

Completion Note

In the final response for a deployment or registration task, state which commit was checked and whether it was found on the remote before the deployment proceeded.