Skip to content

README.md

Latest commit

 

History

History
131 lines (108 loc) · 7.46 KB

README.md

File metadata and controls

131 lines (108 loc) · 7.46 KB
Raw

Deployments

manifest.json is the single machine-readable record of every Wraith deployment on EVM, Stellar, Solana and CKB. Read contract addresses, start heights, artifact hashes and ABIs from it rather than from other files or docs.

deployments/
  schema/v1.json             JSON Schema (draft 2020-12) for the manifest and records
  manifest.json              generated: every record, sorted by chain then network
  evm/horizen-testnet.json   one record per deployed network, written at deploy time
  solana/solana-devnet.json
  ckb/ckb-testnet.json
  stellar/                   written by stellar/deploy.sh on first deployment

Do not edit manifest.json by hand. It is built from the records, and CI fails if the two disagree.

Schema (version 1)

{
  "schemaVersion": 1,
  "deployments": [
    {
      "chain": "evm", // evm | stellar | solana | ckb
      "network": "horizen-testnet", // slug; also the record's file name
      "networkId": "2651420", // see "Network identity" below
      "rpcUrl": "https://…", // public endpoint used by `verify`
      "recordedBy": "chain-query", // deploy-script | chain-query
      "contracts": [
        {
          "name": "ERC5564Announcer", // contract, crate or Anchor program name
          "id": "0x8AE6…", // address / contract ID / program ID / code hash
          "version": "0.1.0", // package or crate version, null if unknown
          "sourceCommit": "…", // 40-hex git commit, null if unknown
          "artifactHash": { "algorithm": "keccak256", "value": "0x…" },
          "abi": { "path": "evm/subgraph/abis/ERC5564Announcer.json", "sha256": "0x…" },
          "deployment": {
            "height": 14202900,
            "txHash": "0x…",
            "deployer": "0x…",
            "timestamp": "…Z",
          },
        },
      ],
    },
  ],
}

A change that breaks existing readers bumps schemaVersion and adds schema/v2.json. Adding an optional field does not.

Per-chain meaning

Chain networkId id deployment.height artifactHash
EVM decimal chain ID contract address block of the creation tx keccak256 of runtime bytecode (EXTCODEHASH)
Stellar network passphrase contract ID (C…) ledger that created the instance sha256 of the wasm (the on-chain wasm hash)
Solana genesis hash program ID slot of the last (re)deploy sha256 of the program ELF without zero padding (solana-verify get-program-hash)
CKB genesis block hash script code hash block of the cell dep tx CKB blake2b-256 of the cell data

Every value can be checked against the chain: npm run verify (below) does exactly that. Chain-specific extras: EVM contracts carry abi (hash over the canonical ABI, so formatting does not matter). Solana programs carry solana.programData and solana.upgradeAuthority. CKB scripts carry ckb.hashType and ckb.cellDep, and external: true marks third-party scripts Wraith depends on (ckb-auth).

recordedBy: "chain-query" means the record was reconstructed from chain state after the fact, so sourceCommit and version may be null. The current EVM, Solana and CKB records are of this kind: they predate the manifest. Records written by a deploy script must carry a source commit.

Consumers

npm run check fails if any of these disagree with the manifest:

File Checked Generated by build
evm/subgraph/subgraph.yaml address and startBlock per data source; undeployed contracts stay 0x…dead no
evm/subgraph/<network>/instant-config.json address, chain, startBlock yes
evm/subgraph/abis/*.json, evm/subgraph/<network>/abis/*.json canonical ABI hash no
evm/hardhat.config.ts chainId of the matching network no
solana/Anchor.toml, solana/programs/*/src/lib.rs [programs.<cluster>] and declare_id! no
ckb/<network>.toml code hashes and cell deps no
stellar/contract-ids.json IDs from stellar-testnet (used by the TS bindings) yes
README.md (between deployments:begin/end) deployed addresses tables yes

Recording a deployment

The tool lives in scripts/deployment-manifest:

cd scripts/deployment-manifest
npm ci
  • EVM: evm/scripts/deploy.ts records automatically on any non-local network, using each contract's deployment receipt. Then update evm/subgraph/subgraph.yaml to match.
  • Stellar: stellar/deploy.sh records automatically, before init.
  • Solana, CKB, or anything deployed by hand: record from the chain.
npm run record -- solana --network solana-devnet --rpc https://api.devnet.solana.com \
  --public-rpc https://api.devnet.solana.com \
  --program wraith_announcer=<program id> \
  --recorded-by deploy-script --source-commit HEAD --version 0.1.0

npm run record -- ckb --network ckb-testnet --rpc https://testnet.ckbapp.dev \
  --public-rpc https://testnet.ckbapp.dev \
  --script wraith-stealth-lock=<cell dep tx hash>:0:data2

npm run record -- evm --network horizen-testnet --rpc <rpc> \
  --contract WraithSender=<address>@<deploy tx hash>

record reads heights and artifact hashes from the chain, merges into the existing record for that network, and runs build. --rpc is only used for queries, so it may contain an API key; only --public-rpc is written to the record. Commit the record, manifest.json and every file build regenerated.

Commands

Command What it does
npm run build Validate records, write manifest.json, regenerate the generated consumers.
npm run check Offline validation of records, manifest and consumers. Runs in CI.
npm run verify Re-read every deployment from its chain and compare IDs, heights and hashes. Runs weekly in CI.
npm test Unit and end-to-end tests for the tool.