Enum Capability 

#[non_exhaustive]
pub enum Capability {
    ReadBalance,
    ProposeTransaction,
    SuggestDestination,
    ObserveEvent,
    SignPayment,
    ReadRules,
    SignRuleCreate,
}

A wallet capability that a toolset may declare in its manifest.

#[non_exhaustive] so that future releases can add capability kinds without a breaking change to downstream consumers that match on the enum.

There is deliberately no SignTransaction variant. Signing is not grantable as a flat capability — the sign-transaction token in a manifest is refused with ToolsetFormatError::BareSignTransactionForbidden.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

ReadBalance

Read the account balance of the agent’s configured account.

Maps to the read-balance token.

ProposeTransaction

Propose a transaction for user review (but not sign or submit it).

Maps to the propose-transaction token.

SuggestDestination

Suggest a destination address for a payment.

Maps to the suggest-destination token.

ObserveEvent

Observe a ledger event (streaming / webhook subscription).

Maps to the observe-event token.

SignPayment

Sign and submit a classic payment transaction (signing-adjacent; gated).

Maps to the sign-payment token.

Inert at declaration

Declaring sign-payment in a toolset manifest confers NOTHING at parse time or install time — unlike the ungated capabilities above, which immediately grant their matrix tool at dispatch. This capability is INERT until the wallet’s first-invoke gate queues an out-of-band user approval and, after the operator approves, converts it into a runtime grant stored in the grant store.

The first-invoke gate fires on every invocation where no current, matching grant exists (first call, expired grant, novel destination / asset / amount-bucket).

Even with a current grant, the per-action payment approval fires unconditionally for every toolset-routed payment. sign-payment NEVER replaces per-action approval; it is an additive first-invoke consent layered before it.

ReadRules

Read the agent’s own context rules (spending-limit budgets, expiry, signer/policy counts) via the read-only rules-observability tools.

Maps to the read-rules token. Separately grantable from read-balance: rule visibility and balance visibility are distinct concerns, so a toolset must request each independently.

SignRuleCreate

Install an agent-proposed context rule on-chain (signing-adjacent; gated).

Maps to the sign-rule-create token.

Inert at declaration

Same posture as Capability::SignPayment: declaring sign-rule-create confers NOTHING at parse or install time. This capability is INERT until the wallet’s first-invoke gate queues an out-of-band operator approval and, after the operator approves, converts it into a runtime grant.

Even with a current grant, the per-proposal RuleProposalSimulated attestation fires unconditionally for every toolset-routed stellar_rule_create_commit call. sign-rule-create NEVER replaces that per-action approval; it is an additive first-invoke consent layered before it — same relationship sign-payment has to the per-action PaymentSimulated approval.

Implementations

impl Capability

pub fn is_key_touching(self) -> bool

Returns true if this capability involves access to the agent’s signing key (either for signing or key-derivation purposes).

This predicate is the single source of truth for the install-time attestation gate. The gate calls this function and NEVER matches the capability variant directly, so that a future key-touching capability forces a compile error here until classified.

The explicit match with NO wildcard arm (_ =>) ensures that every future variant addition requires a conscious classification decision — a compile error here is intentional, not accidental. Any future key-touching capability (such as a key-derivation variant) must be classified as true when added.

Examples

use stellar_agent_toolsets::Capability;

assert!(Capability::SignPayment.is_key_touching());
assert!(!Capability::ReadBalance.is_key_touching());
assert!(!Capability::ProposeTransaction.is_key_touching());
assert!(!Capability::SuggestDestination.is_key_touching());
assert!(!Capability::ObserveEvent.is_key_touching());

Trait Implementations

impl Clone for Capability

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Capability

impl Debug for Capability

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Capability

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Capability

impl Hash for Capability

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Capability

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Capability

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Capability

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Capability