Onboarding

$ mkdir bitcdorg && cd bitcdorg
$ git clone git@github.com:bitcdorg/bitcd-core.git
$ npm install -g @bitcd/core starknet @aws-sdk/client-s3   # the bitcd command; the SDK is for the document store

$ (cd bitcd-core && docker compose up -d --wait devnet ministack)
$ mkdir acme-org && cd acme-org
$ curl -s localhost:5051 -H 'content-type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"devnet_getPredeployedAccounts"}' |
  node -e '
    const a = JSON.parse(require("fs").readFileSync(0)).result;
    const names = ["genesis", "alice", "bob", "carol", "release-bot"];
    const keys = Object.fromEntries(names.map((n, i) => [n, { address: a[i].address, pk: a[i].private_key }]));
    require("fs").writeFileSync("keys.json", JSON.stringify(keys, null, 2));'
$ node -p 'require("./keys.json").alice.address'   # the addresses to put in your file

{
  "name": "acme-org",
  "private": true,
  "type": "module",
  "dependencies": {
    "@bitcd/core": "^0.1.0",
    "starknet": "^9.0.0",
    "@aws-sdk/client-s3": "^3.0.0"
  }
}

$ pnpm install

import { readFileSync } from "node:fs";
import { provider, account, bitcdContract, str } from "@bitcd/core/client";
import { ACTION } from "@bitcd/core/protocol";
import { deployBitcd, runCeremony, signerSpec, policySpec } from "@bitcd/core/ceremony";

const keys = JSON.parse(readFileSync("keys.json", "utf8"));
const p = provider();                                 // BITCD_RPC, default http://localhost:5051
const owner = account(keys.genesis, p);                // the temporary owner

const OPS = str("OPERATOR");
const quorum = policySpec(2, OPS, 1, 1, false);        // threshold, role, min_humans, max_per_operator, allow_open
const person = (op) => signerSpec({ is_human: true, operator_id: str(op), role: OPS });

const signers = [
  { label: "alice", address: keys.alice.address, signer: person("OP_ALICE") },
  { label: "bob",   address: keys.bob.address,   signer: person("OP_BOB") },
  { label: "carol", address: keys.carol.address, signer: person("OP_CAROL") },
  { label: "release-bot", address: keys["release-bot"].address,
    signer: signerSpec({ is_human: false, operator_id: str("OP_CI"), role: OPS }) },
];
const gate = (prefix, action) => ({ label: `${prefix} ${action}`, prefix: str(prefix), action: ACTION[action], policy: quorum });
const policies = [
  gate("GLOBAL", "SET_ROLE"), gate("GLOBAL", "SET_POLICY"),     // managing signers later
  gate("sys", "SET_VALUE"), gate("sys", "TOMBSTONE_VALUE"), gate("sys", "SET_POLICY"),   // the definition
  gate("app/release", "SET_VALUE"), gate("app/release", "TOMBSTONE_VALUE"), gate("app/release", "SET_POLICY"),
  gate("app/flags", "SET_POLICY"),                        // the spare prefix
];

const { address } = await deployBitcd({ owner, deploymentFile: "deployment.json", log: console.log });
await runCeremony({ contract: bitcdContract(address, owner), provider: p, signers, policies, renounce: false, log: console.log });

// runCeremony doesn't read anything back; this is the check the CLI's diff does for you.
const view = bitcdContract(address, p);
for (const s of signers) {
  const on = await view.get_signer(s.address);
  if (!on.active || on.is_human !== s.signer.is_human
      || BigInt(on.operator_id) !== BigInt(s.signer.operator_id) || BigInt(on.role) !== BigInt(s.signer.role))
    throw new Error(`signer ${s.label} differs`);
}
for (const pl of policies) {
  const on = await view.get_policy(pl.prefix, pl.action);
  if (!on.exists || Number(on.threshold) !== pl.policy.threshold || BigInt(on.role) !== BigInt(pl.policy.role)
      || Number(on.min_humans) !== pl.policy.min_humans || Number(on.max_per_operator) !== pl.policy.max_per_operator
      || on.allow_open !== pl.policy.allow_open)
    throw new Error(`policy ${pl.label} differs`);
}
console.log("every signer and policy reads back as written");

$ node onboard.mjs

import { readFileSync } from "node:fs";
import { provider, account, bitcdContract, loadDeployment } from "@bitcd/core/client";

const keys = JSON.parse(readFileSync("keys.json", "utf8"));
const p = provider(), dep = loadDeployment("deployment.json");
const contract = bitcdContract(dep.address, account(keys.genesis, p));
await p.waitForTransaction((await contract.renounce_ownership()).transaction_hash);
console.log(`owner now: ${BigInt(await contract.owner()) === 0n ? "0x0 (renounced)" : "still set"}`);

$ node renounce.mjs
owner now: 0x0 (renounced)

import { readFileSync } from "node:fs";
import { provider, account, bitcdContract, loadDeployment, approveWithSigs, str } from "@bitcd/core/client";
import { ACTION, STORAGE_CLASS, digestOf } from "@bitcd/core/protocol";
import { SELECTORS } from "@bitcd/core/events";
import { s3Store } from "@bitcd/core/store";

const keys = JSON.parse(readFileSync("keys.json", "utf8"));
const p = provider(), dep = loadDeployment("deployment.json");
const view = bitcdContract(dep.address, p);
const store = s3Store({ bucket: "acme-bitcd" });           // BITCD_S3_ENDPOINT
await store.ensureBucket();

const PREFIX = "app/release", KEY = "app/release/prod";
const doc = JSON.stringify({ version: "1.4.0", approved: true });
const cur = await view.get_value(str(KEY));
// SET_VALUE params: key, fingerprint, schema, storage class, the version you expect to replace
const params = [str(KEY), digestOf(doc), str("release/v1"), STORAGE_CLASS.S3, Number(cur.version)];

// 1. Any active signer proposes; the id comes back in the ProposalCreated event.
const bot = bitcdContract(dep.address, account(keys["release-bot"], p));
const receipt = await p.waitForTransaction(
  (await bot.propose(ACTION.SET_VALUE, str(PREFIX), params)).transaction_hash);
const id = BigInt(receipt.events.find((e) => BigInt(e.keys[0]) === BigInt(SELECTORS.ProposalCreated)).keys[1]);
console.log(`proposal #${id}`);

// 2. The document and its claimed params wait beside the proposal, where signers read them.
await store.putText(`${PREFIX}/proposals/${id}.blob`, doc);
await store.putText(`${PREFIX}/proposals/${id}.json`, JSON.stringify({ params: params.map(String) }));

// 3. On a devnet: approve with development keys, then commit (anyone may, once the quorum is met).
await approveWithSigs({ p, contractAddress: dep.address, proposalId: id,
  action: ACTION.SET_VALUE, prefix: str(PREFIX), params,
  signers: [keys.alice, keys.bob], relayer: keys["release-bot"] });
await p.waitForTransaction((await bot.commit(id)).transaction_hash);

// 4. Only a committed document goes where readers look, and only while it's still the current one.
const now = await view.get_value(str(KEY));
if (BigInt(now.digest) === BigInt(digestOf(doc))) await store.putText(`${KEY}/spec`, doc);

$ node first-change.mjs
proposal #1

import { provider, bitcdContract, loadDeployment, str } from "@bitcd/core/client";
import { digestOf } from "@bitcd/core/protocol";
import { s3Store } from "@bitcd/core/store";

const [id] = process.argv.slice(2);
const PREFIX = "app/release", KEY = "app/release/prod";
const p = provider(), dep = loadDeployment("deployment.json");
const store = s3Store({ bucket: "acme-bitcd" });
const doc = await store.getText(`${PREFIX}/proposals/${id}.blob`);
const now = await bitcdContract(dep.address, p).get_value(str(KEY));
if (BigInt(now.digest) !== BigInt(digestOf(doc))) throw new Error(`proposal #${id} isn't the current committed ${KEY}`);
await store.putText(`${KEY}/spec`, doc);
console.log(`${KEY}/spec <- proposal #${id}`);

$ node publish.mjs 1

$ node --input-type=module -e '
    const { s3Store, digestOf } = await import("@bitcd/core/store");
    const doc = await s3Store({ bucket: "acme-bitcd" }).getText(process.argv[1]);
    console.log(digestOf(doc)); console.log(doc);' app/release/proposals/1.blob

$ bitcd diff bitcd.yaml
  SIGNER DIFFERS/MISSING: dave (0x23b7f487…)
  MANIFEST DIFFERS: …
$ bitcd propose-changes bitcd.yaml --keys keys.json
plan: 1 signer change(s), 0 policy change(s)
proposal #…: SET_ROLE dave (OPERATOR, human)
  …
org manifest committed: chain version 3, …

$ bitcd propose-changes bitcd.yaml --keys proposer.json --no-commit
proposal #7: SET_ROLE dave (OPERATOR, human) — needs 2-of-OPERATOR, min_humans 1, max_per_operator 1; sign via `agentgate sign 7`, then run propose-changes again (0 more step(s) after this one, then the manifest)
$ bitcd propose-changes bitcd.yaml --keys proposer.json --no-commit   # before anyone has signed
waiting: proposal #7 (SET_ROLE dave (OPERATOR, human)) needs 2-of-OPERATOR, … — sign via `agentgate sign 7`, then run propose-changes again