H3lm reads your deployed program and the change you are about to push, diffs the Anchor IDL, scores the risk, and returns a verdict. A risky upgrade fails the build instead of reaching mainnet. On an approved upgrade, the node can propose and execute it through your multisig or a single-user gate, behind a time-lock you control.

This SDK is the thin client your CI and tooling talk to. Point it at a node, send an upgrade, read back the decision.

Contents

• Why
• Install
• Quick start
• Verdicts
• API
• Autonomous upgrades
• GitHub Action
• CLI
• Configuration
• Requirements
• Related

Why

An upgradeable Solana program is one transaction away from a different program. A leaked or careless upgrade authority can rewrite storage layout, change who can sign, or wire in a new CPI target. H3lm puts a checkpoint in front of that moment: every upgrade is diffed and scored, and only what passes your policy goes through.

• Catch risky changes before deploy: authority changes, storage layout shifts, new CPI targets, access-control changes.
• Fail the build on BLOCKED or ESCALATED, so CI stops a bad upgrade.
• Keep the veto: the agent never holds your authority alone. It proposes; you approve or veto inside a time-lock window.

Install

npm install @h3lm_infra/sdk

Quick start

import { H3lm } from "@h3lm_infra/sdk";

// Defaults to the public H3lm node. Pass apiBase to target your own node.
const h3lm = new H3lm({ programId, network: "mainnet-beta" });

// The full CI gate: analyze the upgrade, and on APPROVED propose it.
const { decision } = await h3lm.gate({ bufferAccount });

if (decision.verdict !== "APPROVED") {
  console.error(`upgrade ${decision.verdict} (risk ${decision.riskScore})`);
  process.exit(1);
}

A read-only analysis that writes nothing on-chain:

const report = await h3lm.analyze(programId, { currentIdl, newIdl });
console.log(report.verdict, report.riskScore);
for (const flag of report.flags) console.log(flag.id, flag.description);

Verdicts

| Verdict | Meaning | In CI | |---|---|---| | APPROVED | Risk under your approve threshold | build passes | | ESCALATED | Needs a human (e.g. authority change) | build fails, routes to review | | BLOCKED | Risk over your block threshold | build fails |

The score is 0–100 across eight weighted dimensions (authority changes, storage layout, new CPI targets, access control, and more). A protocol-defined policy turns the score into the verdict.

API

const h3lm = new H3lm({
  programId,            // program the agent is assigned to
  network,              // "mainnet-beta" | "devnet" | ...
  apiBase?,             // node URL; defaults to the published node
  policyId?, apiKey?,   // optional
});

| Method | Description | |---|---| | gate(params) | Analyze, and on APPROVED propose the upgrade. Use in CI. | | analyze(target, opts) | One-off analysis. Returns the structured risk report. | | submit(params) | Submit an upgrade buffer and record a decision. | | register(params) | Bind a program to an autonomy path (see below). | | agent() | Onboarding info: agent pubkey, gate program, cluster. | | history(limit?) | The most recent decisions for this program. |

Every method returns a typed result. The shared shapes (Decision, RiskReport, Policy, ...) are exported from the package.

Autonomous upgrades

Bind a program once. After that, every APPROVED gate() is proposed and auto-executed once the time-lock elapses, unless you veto it.

// A) Squads multisig — add the agent as one member, then:
await h3lm.register({ multisig, vault });

// B) Single user, no multisig — point your program's upgrade authority
//    at the node's gate PDA, then:
await h3lm.register({ mode: "gate" });

Get the agent pubkey to add (and the gate program id) from the node:

const { agentPubkey, gateProgram } = await h3lm.agent();

GitHub Action

Gate every release straight from CI:

- uses: actions/checkout@v4
- run: anchor build
- run: npx h3lm run --program ${{ vars.PROGRAM_ID }} --idl target/idl/myprog.json
  # exit code: 0 approved, 2 blocked, 3 escalated

CLI

The package ships an h3lm binary:

npx h3lm run --program <PROGRAM_ID> --idl new.json --current-idl old.json

Exit codes map to the verdict (0 approved, 2 blocked, 3 escalated), so it drops straight into any pipeline.

Configuration

The node URL resolves in this order:

1. new H3lm({ apiBase }) — explicit, always wins
2. process.env.H3LM_NODE_URL — for Node environments
3. the default node baked into the build

Requirements

Node.js >= 18 (a global fetch), or pass your own fetchImpl.

Related

License

MIT © lynewinter