@stellar-registry/perch-interpreter

TypeScript client bindings for the perch interpreter contract (crates/perch-interpreter) — the deployable OpenZeppelin Policy that evaluates compiled perch constraint programs on-chain. This is the client surface a consumer wallet needs to manage programs on a smart account:

• install / uninstall — attach or detach a compiled program for one (account, rule). InstallParams is the RpnProgram plus its provenance: the field named doc_hash holds the rule_hash of the rule the program was compiled from (CANONICAL.md, "Fragment hashes"), not a whole document's hash. A Perch account calls these from apply_doc; the account's own authorization is required.
• get_program — read back the stored InstallParams, so a client can check a program's provenance against the reviewed rule's rule_hash.
• program_version — the program wire-format version this interpreter evaluates (unknown versions are rejected at install time, fail closed).
• enforce — the OZ policy hook itself (normally invoked by the smart account, exposed for completeness/simulation).

import { Client } from '@stellar-registry/perch-interpreter';

const interpreter = new Client({
  contractId: INTERPRETER_ADDRESS, // resolve via the registry / deployment map
  networkPassphrase: 'Test SDF Network ; September 2015',
  rpcUrl: 'https://soroban-testnet.stellar.org',
});

const stored = await interpreter.get_program({
  smart_account: ACCOUNT_ADDRESS,
  context_rule_id: 1,
});

Interpreter addresses are deliberately not baked into this package: resolve them from the content-addressed registry pins. A Perch account reports the interpreter it pins in its infra() view; the recovery-stack deployment's addresses are in deployments/testnet.json, and the release pipeline's canonical registry in docs/testnet-deployment.md.

The sibling package @stellar-registry/perch is the off-chain half: PolicyDoc schema, canonical JSON and hashes (including ruleHash), and the builder. This package is the on-chain client half; the two meet at the provenance hash in InstallParams.

Generated code

src/index.ts is generated by stellar contract bindings typescript from the scaffold-built interpreter wasm — do not edit it by hand. After any change to the contract's exported surface or #[contracttype]s:

just bindings-interpreter-js

then review the diff and rerun the suite. The tests assert the embedded ContractSpec against the frozen golden XDR vectors in testdata/golden/ (the TypeScript check): the two program fixtures encoded through these bindings must reproduce the #[contracttype] bytes the Rust suite pins, byte for byte.

The doc comments in src/index.ts come from the contract's embedded spec and still describe the provenance field as the source document's doc_hash; the description above is the current behaviour.