Module matrix 

Capability→tool matrix, gated capability→tool matrix, and explicit signing denylist.

The UNGATED matrix (grants_for_capability / ALL_MATRIX_ENTRIES) is the admission path for non-signing toolset actions. Tools NOT listed here are default-denied regardless of what capabilities a toolset declares.

The GATED matrix (GATED_MATRIX_ENTRIES) is a SEPARATE tier for signing-adjacent capabilities. It routes SignPayment → stellar_pay_commit ONLY through the first-invoke gate. stellar_pay_commit STAYS in SIGNING_DENYLIST; resolve_action does NOT resolve sign-payment; the ungated ALL_MATRIX_ENTRIES invariant tests iterate the ungated tier only.

Security invariants

Ungated tier

1. {ungated matrix grant tools} ∩ {SIGNING_DENYLIST} = ∅ by literal name.
2. Every ungated matrix tool name EXISTS in the static inventory registry.
3. Every SIGNING_DENYLIST name EXISTS in the static inventory registry (so the denylist cannot silently rot into referencing renamed/removed tools).
4. Every ungated matrix tool has destructive_hint == false (transitive-signing lock).

Gated tier

5. The gated tool (stellar_pay_commit) IS in SIGNING_DENYLIST — this is INTENTIONAL and is the load-bearing invariant proving the ungated path is blocked. The gated tier is NOT in ALL_MATRIX_ENTRIES.
6. The gated tool is reachable ONLY via (four-part check AND a current first-invoke grant) — the end-to-end gate is verified by the MCP server’s integration suite once that crate is added (full tool inventory required at link time).
7. SignPayment grant ∩ {sep43/sep53 bare-sign tools} = ∅.
8. The gated tool exists in the static inventory registry.
9. {flattened GATED_MATRIX_ENTRIES tools} ⊆ SIGNING_DENYLIST (structural proof that no gated tool is reachable via the ungated path). Asserted by gated_matrix_entries_subset_of_signing_denylist.

Inventory-based checks (invariants 2, 3, 4, 8 above) require the full MCP tool inventory at link time and therefore live in the MCP server’s integration suite once that crate is added.

Adding a new tool to the ungated matrix requires:

• Confirming it is NOT a signing/key/policy-mutation tool.
• Adding it to the appropriate capability grant array below.
• Adding a test that verifies it is NOT in SIGNING_DENYLIST.
• Verifying it has destructive_hint == false in the registry.

Adding a new tool to the GATED matrix requires:

• Confirming it IS a signing-adjacent tool that should remain in SIGNING_DENYLIST.
• Adding the capability → [tool_name] entry to GATED_MATRIX_ENTRIES.
• The tool MUST NOT appear in ALL_MATRIX_ENTRIES (ungated tier).
• A new ApprovalKind arm may be required if the grant shape differs.

Adding a signer to an ungated-matrix-listed tool

If a future implementation of an ungated matrix tool adds signing or submission behaviour (e.g. stellar_pay gets an optional sign flag), REMOVE that tool from its matrix grant row before merging. The precedent: signing lives only in *_commit / sep4x_sign_* / sep53_sign_* tools, NEVER in stellar_pay.

Constants

ALL_MATRIX_ENTRIES

All (action_name, granting_capability) pairs in the matrix.

ALL_MATRIX_TOOL_NAMES

All tool names that appear in the UNGATED matrix (deduped, in stable order).

GATED_MATRIX_ENTRIES

All (capability, tool_name) pairs in the GATED matrix.

OBSERVE_EVENT_GRANTS

Tools granted by Capability::ObserveEvent.

PROPOSE_TRANSACTION_GRANTS

Tools granted by Capability::ProposeTransaction.

READ_BALANCE_GRANTS

Tools granted by Capability::ReadBalance.

READ_RULES_GRANTS

Tools granted by Capability::ReadRules.

SIGNING_DENYLIST

Explicit by-name denylist of signing, key-derivation, policy-mutation, and reflexive-escalation tools.

SIGN_PAYMENT_GATED_TOOLS

The single gated-tier entry for SignPayment.

SIGN_RULE_CREATE_AMOUNT_SENTINEL

Sentinel authoritative_amount_stroops value for sign-rule-create gated calls. The amount dimension carries no independent meaning for rule creation; a fixed positive value keeps the (required-positive) bucket check satisfied and makes every sign-rule-create grant/invoke land in the SAME [0, 1] bucket, so re-prompting is driven entirely by authoritative_destination (the smart account), not by this value.

SIGN_RULE_CREATE_ASSET_SENTINEL

Sentinel authoritative_asset value for resolve_toolset_sign_payment_gated calls routing sign-rule-create (Package D, GH issue #8).

SIGN_RULE_CREATE_GATED_TOOLS

The single gated-tier entry for SignRuleCreate (Package D, GH issue #8).

SUGGEST_DESTINATION_GRANTS

Tools granted by Capability::SuggestDestination.

Functions

gated_grants_for_capability

Returns the gated grant set for a signing-adjacent capability.

grants_for_capability

Returns the UNGATED grant set for a capability.

resolve_action

Resolves an action string to a (&'static str, Capability) pair via the CLOSED matrix lookup.