RFC: First-class on-chain program addresses in plugin registry entries

[meanstackofdoom]

Following up on a thread from elizaOS/discussions#7071 where @MrTalecky and I agreed this was worth raising standalone.

The problem

Plugins that interact with on-chain programs — escrow, trading, identity, reputation — are tied to specific deployed program addresses. Today the registry schema (packages/app-core/src/registry/schema.ts) has no field for these. Operators discover them by reading docs, package source, or environment files distributed with the plugin.

That's fine for a curated bundle. It's a real exposure for installable plugins where money moves:

• Drift. A plugin's npm version and the program ID it talks to can desync. We hit this ourselves recently — a devnet redeploy migrated vaultpact to 2chF47Db… and we had to ripple the change through the SDK, dashboard, runbooks, threat model, and seven test files. Anyone who'd installed mid-flight against an old version would have been talking to a stale program.
• Verification. There's no install-time mechanism to assert "the package I just installed talks to the program I expect to talk to." A compromised npm release could redirect to an attacker-controlled program with no on-chain change visible.
• Multi-network. Same plugin, different program addresses across devnet / testnet / mainnet. Currently encoded ad-hoc per plugin.
• Audit scope. External auditors of a financial plugin need a single canonical answer to "which deployed programs does this version trust?" Spreading it across docs and configs makes that question harder than it should be.

What we ship today as a workaround

Holdfast publishes a release-manifest.json alongside each SDK release that pins the on-chain program IDs that version expects. The SDK and our dashboard both consume it at runtime to refuse mismatches. That works for us, but it's per-package convention — there's no way for the elizaOS surface to know about it, surface it to operators, or enforce it.

Proposed addition to commonFields

const onchainProgramSchema = z.object({
  network: z.enum([
    "solana-mainnet", "solana-devnet", "solana-testnet",
    "ethereum-mainnet", "ethereum-sepolia", "base-mainnet",
  ]),
  address: z.string(),
  role: z.string().optional(),       // e.g. "vaultpact", "escrow", "registry"
  releaseManifestUrl: z.string().url().optional(),
});

const commonFields = {
  // ...existing...
  onchainPrograms: z.array(onchainProgramSchema).default([]),
};

For Holdfast, our entry would carry:

"onchainPrograms": [
  { "network": "solana-devnet", "address": "2chF47DbqehX3L38874e2RznaSs46vpcMPEPRYz4Dywq", "role": "vaultpact" },
  { "network": "solana-devnet", "address": "CAZMkHiExVjbsSwAVBYVhz1yaHmnBSvzUYGaQrrRp6yi", "role": "vaultpact_escrow" }
]

Why this isn't just documentation

It changes the contract from "operators figure out which program this plugin talks to" into "the registry asserts which program this plugin version trusts". That makes:

• Install-time checks possible. The runtime can warn or refuse if the resolved program ID doesn't match the registry-declared one.
• Migration auditable. A version bump that changes address is visible in the registry diff, not buried in source.
• Consumer queries cheap. "Which plugins on the registry talk to program X?" becomes a registry query, not a documentation hunt.

Open questions

1. Schema location. commonFields, or only on the pluginEntrySchema subtype: "blockchain" branch?
2. Address typing. Should address be a string or a discriminated union per chain (Solana base58 vs EVM hex)?
3. Manifest semantics. Where does releaseManifestUrl live? Convention? Schema'd format? Out of scope?
4. Separate kind. Is there appetite for a separate kind: "onchain-program" registry entry that plugins reference by id, so the same program can be authoritatively described once and referenced by multiple plugins (reputation reader + escrow writer pointing at the same vaultpact program, for example)?

Happy to PR a concrete schema change once a direction lands. Filed separately from the original Holdfast registry submission so it can be evaluated on its own merits and benefit any financial / escrow plugin.

— Matthew @ Casemate Labs

[musaabhasan]

Strong +1 for making on-chain program addresses first-class in the registry. For plugins that move value or make trust decisions, the registry entry should be sufficient for an operator to verify runtime intent before install, without reverse-reading package source or .env examples.

I would model this as an array rather than a single address, because most serious plugins will eventually have more than one program or deployment role:

onchainPrograms: [{
  chain: "solana",
  network: "devnet" | "mainnet-beta",
  programId: "...",
  role: "escrow" | "reputation" | "identity" | "settlement",
  upgradeAuthority: "..." | null,
  expectedIdlHash: "sha256:...",
  sourceCommitOrTag: "...",
  verifiedAtSlot: 123456,
  status: "active" | "legacy" | "deprecated",
  supersededBy: "...",
  failureMode: "deny-install" | "warn" | "allow-dev-only"
}]

The key security property is not only display, but validation. The plugin manager could fail closed when a value-moving plugin declares a mainnet program whose IDL hash, source tag, network, or upgrade authority does not match the registry metadata. Local overrides can still exist for development, but they should be explicit, visible in diagnostics, and logged as an operator override.

This also gives downstream agents a clean policy hook: character files can say "only use plugins with registry-verified escrow/reputation programs on this network" instead of embedding one-off address checks in agent logic.

[MrTalecky]

Thanks for raising this standalone, Matthew — this is the right place for it.

The drift problem maps exactly to what we hit on the EVM/Base side when we redeployed BackstopRouter + MarketLMSR on Base in late February. The change propagated through deployment config, ABIs, three integration test suites, the indexer, and two SDK consumers. None of that migration was auditable from the registry entry — a reviewer reading the plugin's registry record had no way to know a new program address had been asserted for that version. onchainPrograms in the registry diff would have made that visible at the right layer, before it became an operator support question.

On open question #2 (address typing): discriminated union over plain string, but for a different reason than formatting validation. The fields that compose a complete trust declaration differ by chain. On Solana you want expectedIdlHash and upgradeAuthority alongside the address, as @musaabhasan notes. On EVM you want proxy implementation address, ABI version pinning, and whether the admin key is a multisig or an EOA. Encoding as chain-specific sub-schemas surfaces the right fields per network without nullable key proliferation.

On open question #4 (separate kind): defer to a second RFC. The role field already handles "same program, multiple plugins reference it" for filtering. A standalone kind: "onchain-program" entry becomes worth the complexity when you want the program's trust properties to be asserted independently of any single wrapping plugin — e.g., a shared reputation account consumed by four plugins where each one shouldn't have to redundantly assert the same address and IDL hash. That's a real case, but it's not a v1 blocker.

One addition to @musaabhasan's failureMode enum: the relevant scope on the operator side is sometimes "action" rather than "install". Allow the plugin to install, but refuse to execute value-moving calls if a runtime address check fails. We handle it this way for Base operations — a registry mismatch at trade time returns a structured error rather than blocking the whole plugin at install. A failureScope: "install" | "action" alongside failureMode would let operators express that.