Skip to content

feat: Guardian policy modules (RFC 0002 M2a and M2c) - #602

Draft
zeljkoX wants to merge 108 commits into
mainfrom
251-modules-m2a
Draft

zeljkoX wants to merge 108 commits into
mainfrom
251-modules-m2a

Conversation

@zeljkoX

@zeljkoX zeljkoX commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Implements policy modules from RFC 0002 (issue #251): stages M2a (stateless gates) and M2c (custom Guardian builds). M2b (stateful limits) is deferred past the first release (RFC section 7, open question 1). Supersedes the prototype draft #554.

What it does

Operators declare module instances in a TOML catalog (GUARDIAN_MODULES_CONFIG). The Guardian calls them at three gate hooks and refuses what a module denies:

  • before_account_registered: /configure
  • before_proposal_created: proposal creation
  • before_transaction_approved: the ack on push and on Guardian execution

Module kinds

  • Four built-in policies run in process: spending-limit, recipient-policy, signer-policy and code-policy.
  • Remote modules are called over gRPC (guardian.module.v1).
  • Custom kinds compile into your own server build.

Operator API (/dashboard/modules)

  • Global params, per-account layers and assignments, all with an optional expected_version.
  • Enable and disable, and the params history.
  • New permissions policies:write, policies:write_global and modules:disable.

Clients

  • Policy discovery (GET /policies) and a dry-run check.
  • Typed refusals in the Rust and TypeScript SDKs.

Failure handling

  • Per-instance on_error and a circuit breaker.
  • An evaluation budget and a request size cap.
  • Health probes, and startup during a module outage.

guardian-module-sdk crate

  • The Module trait and the serve harness.
  • A conformance suite and the built-in policies.

Examples

  • examples/policy-module: the built-ins as a remote service.
  • examples/custom-guardian: a custom build.
  • examples/compliance-module: KYC on signers, plus sanctions or allowlist screening of recipients.

Docs, operations and qualification

  • Guides in docs/guides/policy-modules/ and a runbook.
  • Configuration, dashboard and troubleshooting reference.
  • Alarms in infra/ (circuit open, fail-open).
  • Deterministic qualification scenarios.

Storage

  • Filesystem and Postgres stores.
  • Four migrations, all additive.

Review history

  • RFC 0002 is at revision 35. Earlier review rounds are recorded in its appendix.
  • A four-reviewer red-team pass on 2026-11-17 found:
    • a P2IDE reclaimer bypass in recipient-policy;
    • malformed deny codes being let through on fail-open instances;
    • a registration probe by non-cosigners;
    • lost updates on concurrent operator writes;
    • lifecycle holes.
  • All were fixed in 27f45897 and followed by independent re-reviews.

Testing

  • Unit tests:
    • server lib: 1,829 pass;
    • module SDK and the two example crates;
    • qualification driver: 116 pass;
    • TypeScript operator client: 122 pass.
  • Static checks: clippy with CI settings, fmt and the OpenAPI drift check are clean.
  • TLA+ models: auth-replay, guardian-switch, candidate-queue, guardian-execution and proposal-lifecycle pass. Fingerprint drift was reviewed and accepted.
  • Deterministic qualification: 24 of 25 scenarios pass, with full coverage claimed, on 0160b3cd. The one skip (det-operator-audit) has no Rust driver yet.

Before merge

  • Merge main (b74a017b: session operations GetPolicies and CheckDeltaProposal moved to 15 and 16, after the released GetStateTail = 14).
  • Postgres suite on 4ba5a5d7: 117 passed.
  • Deterministic qualification on 4ba5a5d7: 24 of 25 passed, 1 skipped (det-operator-audit, no Rust driver), claim full. Image built with thin LTO on an 8 GB Docker VM.
  • Manual smokes T058 to T060 (speckit/features/251-guardian-modules/tasks.md), including the quickstart walk-through against a local node.
  • Apply the new alarms in a modules-enabled environment. CloudWatch only checks the Metrics Insights queries on apply.

…nd harness (#251)

Protocol version 1 types (guardian.module.v1), the Module and ModuleFactory
traits, the serve harness for remote modules with per-instance credentials,
the basic-policy reference module, and the conformance test. Carried from
the prototype (#554); RFC 0002 revision 26.
crates/server/src/modules: catalog loading and validation, the kind
registry (basic-policy in process, grpc remote), the ordered pipeline with
global and account layers, request assembly with account views and the
Miden projection, module state on the filesystem and Postgres (migration
2026-10-15 guardian_modules), and the /dashboard/modules operator routes
under policies:write, policies:write_global and modules:disable, with audit
and params history. Loaded from GUARDIAN_MODULES_CONFIG into AppState; no
hook calls the pipeline yet. Carried from the prototype (#554).
before_transaction_approved runs in ack_delta_internal::acknowledge_applied,
shared by push_delta and the execution worker; before_proposal_created in
push_delta_proposal, with the dry-run check (POST /delta/proposal/check)
and the policy summary (GET /policies) on both transports;
before_account_registered in configure_account, ahead of the account claim.
Approvals are recorded on the signed delta's metadata.

A refused Guardian execution ends with GUARDIAN_EXECUTION_MODULE_DENIED or
GUARDIAN_EXECUTION_MODULE_UNAVAILABLE in guardian-shared and the TypeScript
execution vocabulary; ExecutionFailureCode is no longer Copy. Carried from
the prototype (#554).
guardian-client (Rust): ModuleRefusal and ClientError::module_refusal,
check_delta_proposal and get_policies. miden-multisig-client (Rust):
MultisigError::ModuleDenied and ModuleUnavailable kept typed on proposal
creation, push and registration, MultisigClient::get_policies and
ProposalBuilder::check. @openzeppelin/guardian-client: module meta fields,
GuardianHttpError.moduleRefusal(), checkDeltaProposal and getPolicies.
ModuleRefusal re-exported from the TypeScript multisig package. Carried
from the prototype (#554).
)

docs/guides/policy-modules (built-in, remote and custom modules), module
configuration, dashboard routes and permissions, troubleshooting codes,
spec/api.md execution failure codes, RFC 0002 revision 26, the speckit
plan, tasks-p0.md (prototype record) and tasks.md (M2a), and the
verify-module-counting TLA+ skill for RFC sections 3.3 and 3.4. Carried
from the prototype (#554).
Five layers, each building and testing on its own, with the rule that a
TypeScript vocabulary held to Rust by a drift test lands with its source.
…251)

guardian_module_v1.proto now follows the RFC's renumbered version 1. The
Guardian fills what it adds: HookRequest.network_id from the account's
registered network (an EVM account is refused rather than mislabelled),
submitter_session for a request signed by a delegated session key on
pushes, proposal creation and Guardian executions, AccountView.code_commitment
and procedure_roots, procedure_thresholds limited to overrides that apply
on chain (non-zero, on an exported procedure, not the auth procedure), and
MidenTransaction.reference_block, expiration_block only when the
transaction expires, and new_code_commitment when it replaces the code.
…n 1 (#251)

A session key authenticates requests but cannot add a cosigner approval, so
whether a session created a proposal adds nothing the threshold does not
already require, and no catalog policy uses it. Removed from
TransactionSubject, PendingTransaction and CommitEvent before the freeze,
unverified_metadata renumbered to 5; version 1 can add it later as a new
field. Section 3.2 corrected for #580: pushes and Guardian executions accept
session credentials, so submitter_session is set at the ack. Spec FR-039,
research and tasks follow (T008 dropped).
…le approval (#251)

The approval written to a signed delta's metadata now carries signed_at,
fixed before the pipeline runs and sent to the modules as accounting_time,
the submitter it was evaluated for, and the matching proposal's creator,
next to the catalog hash, params version and fail-open list. The pipeline
returns only the configuration it ran with; the ack builds the record.
Delta metadata is already stored on both backends, so this needs no
migration. OpenAPI regenerated.
…s the delta (#251)

NetworkClient::apply_delta_with_module_views verifies and applies a delta
and returns the policy module views of its base and result; the Miden
client builds both from the accounts it already decoded, where request
assembly decoded the state JSON again for each view. The ack and proposal
creation seed the plan's view cache with them, only when modules are
configured, so a server without modules does no extra work. A view that
cannot be extracted is not seeded and still fails the modules, never the
push. The default implementation decodes separately, so other networks and
test doubles behave as before.
…onents (#251)

Single-key Falcon and ECDSA accounts, a 2-of-3 Falcon guarded multisig, and
a mixed-scheme guarded multisig with a procedure override, built with the
miden-standards components, read back as built: signers in order with
their schemes, thresholds, code commitment and procedure roots. An
override on the auth procedure, which the upstream builder accepts but
which changes nothing on chain, is left out.
…criteria (#251)

Generated protocol code allows clippy's large_enum_variant: the
HookRequest subject oneof is generated by prost. The protocol version 1
freeze (T012) now follows the criteria that are behaviour rather than
fields: the dry run with approval instances, the lost-claim registration
and the basic-policy code allowlist.
A real basic-policy cap refuses a payment over it through a stored
proposal, through an offline push without one, and under a misleading
proposal label, storing nothing; a Guardian execution over it ends
GUARDIAN_EXECUTION_MODULE_DENIED before anything is proved. Without a
catalog a push builds no view or projection and records no approval.
…judge without a projection (#251)

Each basic-policy rule denies with a fixed reason code and a fixed
client message naming the rule, never a list entry or a limit, so a full
denial discloses no params; the details stay in the logged message. An
unknown recipient refused under deny_unknown_recipients reports the
denylist rule (recipient_blocked), as RFC 0002 section 3.1 specifies. A
transaction without a Miden projection is now a module error, so
on_error applies, instead of a projection_missing denial.
… line (#251)

Every module and layer called in one hook invocation receives the same
HookRequest.request_id, and the next invocation a new one, so module logs
join the Guardian's. A denial is logged with request_id, account, hook,
module, submitter, layer, reason code, the module's message, catalog hash
and params version, including a generic denial whose client sees none of
it.
…nd health probe (#251)

Each hook invocation gets GUARDIAN_MODULE_EVALUATION_BUDGET_MS (default
1000): a call gets the smaller of its timeout and what is left, and once
the budget is spent later modules count as timed out. A request whose
encoded size exceeds GUARDIAN_MODULE_REQUEST_MAX_BYTES (default 2 MiB) is
a module failure and is not sent. Each replica keeps a breaker per
instance: GUARDIAN_MODULE_BREAKER_FAILURES consecutive failures (default
5) open it, so the module is skipped and its on_error applies at once; a
Describe probe every GUARDIAN_MODULE_PROBE_INTERVAL_MS (default 5000)
half-opens it and the next call decides. A deny is an answer, and a call
cut short by the budget or refused for size is not the module's failure.
A bad value in any of the four variables refuses startup.
…ites (#251)

In the prod stage the server refuses to start when, for any hook, the
timeouts of the instances every new account receives exceed the
evaluation budget, or when the budget is not below the execution
reservation lease. Assigning modules to an account or setting an account
layer is refused when the account's worst case (each all instance, again
for its layer, plus each assigned one) could exceed the budget. Accounts
already stored over the budget are logged at startup without blocking it,
so a deploy that raises a timeout cannot become an outage.
…d circuit state (#251)

Module evaluations are measured per instance and outcome (allow, deny,
error, skipped), with fail-open passes counted, and gauges for the probe
result, open circuits, enabled and drifted instances, the loaded catalog,
and the accounts over budget and orphaned rows found at startup.
GET /dashboard/info reports the replica's module catalog hash
(backend.module_catalog_hash, null without a catalog), parsed by the
operator client, and GET /dashboard/modules each instance's circuit on the
answering replica. OpenAPI regenerated.
…odule metrics (#251)

docs/CONFIGURATION.md documents GUARDIAN_MODULE_EVALUATION_BUDGET_MS,
GUARDIAN_MODULE_REQUEST_MAX_BYTES, GUARDIAN_MODULE_BREAKER_FAILURES and
GUARDIAN_MODULE_PROBE_INTERVAL_MS, with the rule that client request
timeouts must exceed the budget; spec/api.md lists the guardian_module_*
metrics. Exporting them through CloudWatch and Grafana is task T063.
…wlist (#251)

A first configuration that loses its claim to a concurrent one is judged
again by before_account_registered against the account it lost to, with
that account's stored state as before, and only then consumes its replay
timestamp; a denial there stores and consumes nothing.

basic-policy gains allowed_code_commitments with code_check: under
changed (the default) the code an account registers with and code a
transaction replaces it with must be listed, so accounts already on other
code keep working until they change it; under all, the code an account
runs is checked at every gate hook. It refuses with code_not_allowed.
…a check (#251)

POST /delta/proposal/check now runs the before_proposal_created
instances and then those subscribed only to before_transaction_approved,
so rules that must hold at approval answer the check as well; an instance
on both hooks runs once. Every request in a check carries
HookRequest.dry_run = true; real proposal creation does not. complete is
false whenever the catalog has an enabled transaction gate instance that
opts out of checks, whether or not it applies to the account, so the
answer reveals nothing about one account's instances.
…cript (#251)

Multisig.getPolicies lists the rules GUARDIAN discloses for the account,
and Multisig.checkTransaction checks a transaction before proposing it:
one variant per typed create*Proposal method, built by that method's own
code on a short-lived view whose push becomes a check, so the check
judges exactly the payload proposing would send and nothing is stored.
Both mirror the Rust MultisigClient. Tests show a creation refusal
reaching callers as the typed refusal in the Rust and TypeScript base
clients and SDKs, and the four client READMEs document refusals, the
policy listing and the check.
The freeze criteria of RFC section 7 are implemented with tests: the
renumbered proto, registration before the claim including the lost claim,
network_id, code and procedure fields, reference and expiration blocks,
new_code_commitment, submitter_session, the dry run with approval
instances, and the basic-policy code allowlist. From here guardian.module.v1
changes only additively; the proto copies and RFC section 7 record it.
…ation (#251)

A scope = "default" instance judges a new account's registration with its
current global params, and once the request has claimed the account every
enabled default instance is copied into its assignment with exactly those
params. ModuleStore::seed_assignment writes the copy only into an account
with no assignment and no assignment history, under the module state lock,
so an operator write wins; a crash between claim and copy leaves an
unfinished claim whose retry copies again. Existing accounts never receive
defaults, and a refused or lost registration copies nothing (RFC 0002
revision 29). Default instances count in the budget like assignments.

Account views report each row's real scope and an orphaned flag, and
GET /dashboard/modules lists stored instances the catalog no longer
declares under undeclared.
…nated history (#251)

Every operator params write is refused with invalid_input when the params
exceed GUARDIAN_MODULE_PARAMS_MAX_BYTES (default 64 KiB, compact JSON with
sorted keys), before the module is called, and a catalog seed over it
refuses startup. params_drift and the drift metric compare the catalog
file with the params seeded from it, so operator writes and module
migrations no longer read as drift. GET /dashboard/modules/{id}/params/history
returns newest first, paginated with ?before=<version>&limit=<n> (default
100, at most 1,000).
The nine /dashboard/modules and account module routes are annotated with
their bodies, views, permissions and errors and appear in the dashboard
and combined OpenAPI documents; the view, body and history types derive
ToSchema. T043 is dropped: the RFC migrates account layers and assignments
when they are next written.
…he conformance suite (#251)

- basic-policy: a faucet or recipient is an account id of 30 hex digits and a signer or code commitment is 64, so an id cut short when pasted, or an account id where a commitment belongs, is refused when the params are validated instead of never matching.
- Conformance: a request can state what it must be answered with (allows, denies, denies_with a reason code, fails), and a suite needs at least one request the module must deny. A module that allows everything answered consistently and conformed.
- Test ids in the SDK and in the server tests that feed basic-policy are real lengths.
…ges follow fixes (#251)

- A health probe that gets no answer counts as a failed call. One that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with opens the breaker at once and keeps it open until a probe passes: a module redeployed under a running Guardian was trusted until restart.
- The over-budget and orphan counts are taken again every minute, so an alarm clears after the operator fixes the assignment.
- The count reads which module each account row names, not every account's params, which default copies make as large as the account count times the params size.
…ase call (#251)

Every module write takes the module_state_version row lock. The copy a first registration writes held it across about ten round trips for three default modules, so registrations and operator writes queued behind each one. guardian_module_seed_assignment takes the lock, checks the account and writes its rows and history inside one statement.

Local A/B on the Postgres store (600 copies of three modules): 290 to 390 copies per second before, 1750 to 3400 after; single-call p50 from about 3 ms to 0.4 ms. Table in research.md.
#251)

- guardian_modules_config injects GUARDIAN_MODULES_CONFIG, the catalog's path inside the image; the catalog travels in an image built from the published one.
- guardian_module_secret_names grants the task runtime role GetSecretValue on exactly those secrets and sets GUARDIAN_MODULE_SECRET_PROVIDER=aws.

Both are empty by default, which leaves the stack as it was. Validated with terraform validate; not applied.
#251)

- services.md: the modules subsystem and the three handlers that call it.
- MULTISIG_SDK.md: policy listing, the proposal check and typed refusals in both SDKs.
- backup-restore.md: module state is in the database; the catalog and module secrets are not; what a restore rewinds.
- MIDEN_COMPATIBILITY.md: new error codes and the Rust enum changes.
- Configuration, troubleshooting, runbook and RFC: the probe's effect on the breaker and the gauge recount; id lengths in the basic-policy guide and examples.
…mes anyone (#251)

A partial note, or one that is neither P2ID nor P2IDE, has no recipient the denylist can read, so a blocked recipient could be paid through one. deny_unknown_recipients is now on by default whenever recipient_denylist is not empty; false opts out, and true applies it to an empty list too. An empty denylist stays lenient: it has nobody to hide, and the guide's blocklist starts empty on every account.
…g can require an instance (#251)

- An enabled instance that has started on this Guardian before, and whose module does not answer its startup checks, starts unavailable: its breaker is held open, so its accounts follow on_error, and each health probe runs the full startup checks until they pass. A third party's outage no longer keeps every replica from restarting. An instance new to this Guardian must answer, and a module that answers but refuses the call, the params or the protocol version still stops startup.
- An instance the catalog declares enabled and not operator-disableable is enabled at startup when it is stored as disabled, with a params history entry by the catalog: no operator may hold it off under that catalog. Other differences still follow the stored flag.
- Startup check failures are typed (unreachable, incompatible, invalid params), which the probe and the breaker use.
…nces, the denylist default (#251)

Configuration reference, guides, runbook and RFC 0002 revision 32.
…ms (#251)

basic-policy enforced five unrelated rules from one params object. It is replaced by four first-party kinds, one concern each:

- spending-limit: max_per_transaction, allowed_assets (proposal creation, transaction approval)
- recipient-policy: allowlist or denylist, deny_unknown (proposal creation, transaction approval)
- signer-policy: allowlist or denylist, check (all three hooks)
- code-policy: allowed, check (all three hooks)

Each kind refuses params that belong to another and supports only the hooks where its rule can refuse something, so a catalog that subscribes a spending or recipient rule to registration does not start. A recipient allowlist and denylist can no longer be set together. An instance with no rule allows without reading the request; one with a rule that cannot read what it needs is an error, so on_error applies. Reason codes and client messages are unchanged, so the client SDKs need no change.

The SDK exposes guardian_module_sdk::policies (SpendingLimit, RecipientPolicy, SignerPolicy, CodePolicy, KINDS) with one conformance suite per kind. examples/policy-module serves any of them with --kind. The qualification stack's qual-gate and qual-switch are signer-policy, and a new qual-cap (spending-limit) carries the live cap scenario.
…racts (#251)

The built-in guide documents each kind with its own params table and the hooks it supports; catalogs, remote and custom guides, READMEs, the qualification doc, the speckit contracts and RFC 0002 section 3.1 use the new kinds, recorded in revision 32. Completed tasks and planning notes keep the old name as history.
…it (#251)

Both SDKs now split proposal creation into a draft step (summary,
metadata and unsigned payload) and either a push or a policy check of
that same draft. The check no longer intercepts the create path: the
Rust dry-run flag and shared mutex, and the TypeScript prototype
override and thrown sentinel, are gone. Public APIs are unchanged; the
Rust draft type stays crate-private.

Rust custom proposals use the same draft, which adds
check_custom_transaction and closes the gap with TypeScript, which could
already check custom proposals. The mock Guardian records check
requests, and a test pins that a check sends exactly the payload a push
sends, without the proposer's signature.

The client-sync TLA+ mirrors point at the moved TypeScript functions and
its fingerprints are re-recorded; the model is unchanged.
…no lock (#251)

Every module write used to lock and bump the one module_state_version
row. That row was also the replicas' instance cache key and the version
each signed delta recorded, so registering an account with default
modules waited for every other registration and operator write and made
every replica reload its instances.

module_state_version now moves only on instance writes (global params,
enabled flags). Each account has its own version in the new
module_account_version table, bumped and locked by writes to that
account's layers and assignment, including the default copy at
registration, which is refused once the account's version is non-zero.
The evaluation snapshot returns both versions in one call. Signed
deltas, fail-open audit events and denial logs record params_version and
account_params_version; account writes are audited with the account
version; the operator account view reports it. History entries carry
the version of their own counter and an id, and the history pages by id
(before=<id>), with a (module_id, id) index.

The filesystem store keeps both counters in its state file, moving each
once per write including writes that change nothing, and upgrades an
older file from its history. The down migration restores the single
version above every recorded one.

Operator client types and parsers, OpenAPI, the dashboard, runbook and
troubleshooting docs, RFC 0002 section 2.2 and the speckit data model
are updated.
#251)

pipeline.rs held startup reconciliation, the instance cache, planning,
the evaluation loop, budget reporting, the health probe and their tests
in one file. It is now pipeline/ with:

- mod.rs: evaluation (the cache and snapshot, planning, Plan::run,
  failure handling);
- startup.rs: ModulePipeline::new in named steps (read the stored
  instance rows, apply them to the catalog, build and check the
  instances, then the startup writes: catalog-required enables, seeds of
  new instances, params a module migrated), so nothing is written before
  every instance passed its checks;
- budget.rs: the per-account budget check and the over-budget recount;
- probe.rs: the health probe loop and the state gauges.

No behaviour change: every function and test body is HEAD's apart from
module paths, and the tests moved with their topic.
…251)

live-module-recipient-1of1-ecdsa assigns the stack's new qual-recipient
instance (recipient-policy, params disclosed) with a denylist naming the
funding faucet, which the scenario never pays, and reads it back through
the account's own policy listing. A payment to the faucet is refused at
the check and at creation with recipient_blocked; a payment to the
treasury passes, is signed by GUARDIAN after the approval hook runs on
the real transaction, and lands. The denylist names someone, so
deny_unknown is on and a fee note read as a payment would refuse the
send.

New actions module-recipient-assign and module-recipient-refuses in the
Rust and TypeScript drivers; the cap scenario's assign step shares their
helper. Required on testnet, excluded on devnet like the cap scenario.
The smoke harness drives every module call of the operator client: the
catalog with enable and disable per instance, the params history paged
by entry id, an account's modules with its params version, and the
writes (global params, setting or clearing an account layer, replacing
the assignment). Params are checked as JSON objects in the browser and
every write takes a reason.

Errors now show the HTTP status before the error code, so a missing
permission reads as HTTP 403. Changing the signer or logging out clears
the module state. The README shows how to start Guardian with the
guide's built-in catalog and which operator permissions each action
needs, and the smoke-test skill lists the panel.
…on the request path (#251)

Policy module requests decoded on the async request path: the
transaction summary a second time for the projection, and at
registration the initial state twice and the stored state once more.
The account views of a push already came from the apply decode, through
a per-replica cache by state commitment.

The decode that verifies and applies a delta now also returns the
projection (apply_delta_with_module_inputs, ModuleInputs), with the
chain fee loaded before it, and registration decodes each state once
(module_account_inputs), all inside the reconstruction task. Request
assembly only copies finished parts and decodes nothing; the view cache
is removed. The ack path reads the module plan before the
reconstruction, so no inputs are built for an account no module applies
to; Applied carries the plan and inputs in a private field, so only
apply_to_base builds one. Without a catalog nothing changes.

An input that cannot be extracted is still a module failure under
on_error. Tests pin one build of each input per push, none for a module
on another hook, on_error deciding a failed projection, and the apply
decode's projection matching a separate decode. A local before/after
benchmark shows no regression; RFC 0002 sections 3.2 and 4.3 and
research.md describe the change and the numbers. Six TLA+ models
re-fingerprinted for the call-site changes; all pass.
…#251)

A module request the Guardian could not build (an account view or the
projection could not be extracted, a proposal or stored-state read
failed) or one over GUARDIAN_MODULE_REQUEST_MAX_BYTES was a module
failure, so an on_error = "allow" instance let it through. Both are
under the requester's control: padding a transaction or registering an
account whose state cannot be read skipped every fail-open module, such
as a sanctions screen, for the requester's own transactions.

on_error now covers only the module's own failures (timeout, error,
invalid decision, open circuit). A request that cannot be built is
refused with GUARDIAN_MODULE_UNAVAILABLE (retryable, since some causes
are transient); one over the cap is denied with GUARDIAN_MODULE_DENIED
and reason_code request_too_large, or the generic denial for a generic
instance. Neither counts toward the circuit breaker, and both are
counted in guardian_module_request_refused_total{module, reason},
exported to CloudWatch. No new wire codes.

RFC 0002 sections 3.4, 4.2 and 4.4 record the change and two decisions
not to change code: breakers stay per instance (every hook is reachable
by any account holder on their own account), and Guardian execution
denials stay at the ack (an earlier check would be a second evaluation).
Configuration, troubleshooting, runbook, SDK error docs, the speckit
spec and OpenAPI updated.
Brings in #588, #590, #591, #592 and #594.

- #590 (decode the push tail once, one CPU gate permit) and the module
  inputs built in the reconstruction decode: TailAdmission builds the
  module inputs from the account its gate decoded, so a gated push still
  decodes the tail once. ApprovalPlan reads the before_transaction_approved
  plan (and loads the fee) before the reconstruction task, and is the only
  way to an Applied, refusing as unavailable a plan applied without inputs.
  NetworkClient gains verify_and_apply_delta_to_account_with_module_inputs.
- #592: the account id check comes from guardian_shared on every path,
  including the module-input apply paths, which its test now covers.
- #594: the applied-nonce rule replaces the branch's chained-delta check in
  push_delta and runs in acknowledge_delta.
- #591: TS signOnCreate and the built_here / caller_supplied push checks
  move into pushDraft; checks still send an unsigned draft.
- TLA+ fingerprints re-recorded for the merged push_delta, TailAdmission,
  pushDraft and the branch's worker and configure functions; all nine
  models pass.
…0002 M2c)

ServerBuilder::from_env() holds the environment wiring the server binary used
to inline, so the official main.rs and every custom build configure the same
way. from_env and build return BuildError, a std::error::Error, instead of
String.

examples/custom-guardian replaces the custom_module_server example: the
official server plus the note-policy kind, with a Dockerfile on the official
toolchain and base. scripts/custom-guardian-template.sh turns it into a
standalone per-release template: guardian-server and guardian-module-sdk at
the release tag, a [patch.crates-io] so crates.io module crates share the
release SDK, and the release Cargo.lock with a check that no other pinned
version moves. The Custom Guardian Template workflow builds the template and
its image with --locked on every release and attaches
custom-guardian-<tag>.tar.gz.

Docs: RFC 0002 revision 33, the custom modules guide, server README,
MIDEN_COMPATIBILITY and TROUBLESHOOTING (startup message wording), speckit
tasks T100 to T104.
- Refresh the chain fee once at a time, with a 10 s cooldown after a
  failed read; a request does not wait for a refresh when a value is known.
- Store the params a module migrates when it recovers from a startup outage.
- Seed the default modules on a finished claim only when the account has
  no module history (no layer and no assignment), so an operator's
  configuration made during registration is kept.
- Compare module tokens without leaking their length.
- Correct docs and logs that described a refused-as-unavailable path as
  fail-open; replace inline comments with named helpers.
- RFC 0002 revision 34: stateful modules (M2b) deferred past the first
  release; spec and tasks updated to match.
…params

spending-limit and recipient-policy now take a faucet or recipient as its
Miden bech32m account address as well as its 0x hex id. The address is
checked as Miden checks it (account type byte, id length, routing part
checksum) and validate_params returns the params with the hex id, so the
Guardian stores, shows and matches hex. Params already in hex are stored
as sent. Signer and code commitments stay hex only.
Security and policy correctness:
- Project the reclaimer of a reclaimable P2IDE note (OutputNote.reclaimer)
  and judge it in recipient-policy, so an allowed target cannot carry a
  payment to a blocked account.
- A module deny with a malformed reason code is a deny (policy_denied), not
  a module failure that on_error = "allow" would sign.
- Registration by a key the account does not list (including a lost claim
  race) consumes its timestamp and is vouched for before any module runs.
- Hook requests carry the account id in lowercase.

Operator API and state:
- Optional expected_version on params writes; a stale write gets 409
  GUARDIAN_MODULE_PARAMS_STALE, checked inside each store's write lock.
- Refused module writes return the reason in meta.detail (capped); bodies
  naming a JSON key twice are refused.
- Seeds keep the catalog params as written, so normalization is not drift;
  params moved out of the catalog file are adopted instead of {}.
- Disabled default instances are still copied at registration; rows left by
  a scope change are reported as orphaned; unchanged assignment entries are
  not re-validated and a module outage returns 503.
- A late answer no longer closes an open breaker; transitions are reported
  under the lock.
- A prod server with module state but no catalog refuses to start unless
  GUARDIAN_MODULES_DISABLED=true (Terraform: guardian_modules_disabled).

SDK, clients, infra and docs:
- serve() refuses every call until an instance is registered, unless
  allow_unauthenticated(); the note-policy example errors on requests it
  cannot read.
- Operator client: expectedVersion option and error detail.
- Module circuit-open and fail-open alarms.
- Catalog field reference, wire contract for non-Rust modules, rollback
  section, corrected guides, RFC 0002 revision 35.
examples/compliance-module is a custom remote policy module on the module
SDK: every signer must be KYC-verified (at registration and on
transactions), and payment recipients (P2ID target and P2IDE reclaimer)
are screened against a blocklist or an allowlist. The lists come from a
JSON file read at startup; each catalog instance's params choose which
checks apply. The conformance suite covers every rule.

docs/guides/policy-modules/compliance.md walks through running it with a
Guardian (tokens, catalog, expected log lines, steps to try), the reason
codes, changing the lists, production notes, what the Guardian cannot
screen, and how to swap the file for a database. compliance.toml is
parse-tested with the other guide catalogs.
…le artifacts

M2b is deferred past the first release, so version 1 as first published
carries only the stateless contract. Removed from the proto, the SDK trait
and the serve harness: the Notify and NotifyGap RPCs, CommitEvent, Gap,
NotifyAck, TransactionSubject.pending with PendingTransaction and
PendingState, the after_transaction_committed hook value, and the notify
and notify_gap trait methods. Nothing called them, and a module that
implemented notify would start fine and count nothing. M2b adds them back
as the notify capability within version 1. RFC 0002 section 3 matches the
SDK proto again, and the passages that described the removed parts as
current now mark them as M2b.

Also removed: the speckit copy of the proto (drifted from the SDK's), the
prototype task list tasks-p0.md (in history), and the verify-module-counting
skill, which models M2b and stays with that work.
The JSON file keeps the example self-contained; a real module reads its
lists from its own database, a screening vendor or an on-chain registry,
depending on its compliance requirements. The guide lists those sources,
how to pin an on-chain registry, and how to refresh any of them.
@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

let error = client
.push_delta_proposal(
&create_test_account_id(),
1,
assert!(policies.policies[0].params.is_some());

let passed = client
.check_delta_proposal(&account_id, 1, serde_json::json!({ "tx_summary": {} }))
assert!(!passed.complete);

let refused = client
.check_delta_proposal(&account_id, 0, serde_json::json!({ "tx_summary": {} }))
Brings in #595 (candidate queue tail, base commitment check) and #596
(v0.19.0-rc.2). Session operation ids: GetStateTail keeps 14 as released;
GetPolicies and CheckDeltaProposal move to 15 and 16, with the shared
vectors regenerated. Proposal drafts carry main's base commitment, so the
check and the push both send it. OpenAPI and model fingerprints regenerated.
The drift guard against GuardianError::code() caught the code the server
added for a stale expected_version on a module params write.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants