Crate exo_economy 

exo-economy — custody-native transaction economy

This crate provides the deterministic, integer-only quote/settle/ receipt scaffold for EXOCHAIN’s custody-native economy. The launch phase resolves every active fee, vigorish, multiplier, share, and settlement amount to zero, so trust is never paywalled. The full economic mechanism still runs end-to-end so that future governance amendments can flip pricing on without reshaping the type system.

Determinism contract

• Integer-only (MicroExo = u128, BasisPoints = u32).
• All hashing is BLAKE3 over canonical CBOR.
• Checked arithmetic fails closed on overflow or underflow.
• Only deterministic ordered collections (BTreeMap, BTreeSet), never the unordered standard-library variants. No floating-point arithmetic anywhere in the price path.
• Quote and receipt hashes are deterministic and tamper-evident.

Zero-launch guarantee

PricingPolicy::zero_launch_default is the canonical launch policy. Every active price field is 0, every multiplier is the neutral 10_000 basis points, and the global ceiling is 0. The deterministic pricing formula therefore clamps charged_amount to 0 for any inputs.

High-level API

use exo_economy::{
    ActorClass, AssuranceClass, EventClass, InMemoryEconomyStore,
    EconomyStore, PricingInputs, PricingPolicy, quote, settle,
    SettlementContext, ZeroFeeReason,
};
use exo_core::{Did, Hash256, Signature, Timestamp};

let mut store = InMemoryEconomyStore::new();
let policy = store.get_active_policy().unwrap();

let inputs = PricingInputs {
    actor_did: Did::new("did:exo:agent").unwrap(),
    actor_class: ActorClass::Holon,
    event_class: EventClass::HolonCommercialAction,
    assurance_class: AssuranceClass::Standard,
    declared_value_micro_exo: Some(1_000_000),
    realized_value_micro_exo: None,
    compute_units: 100,
    storage_bytes: 4_096,
    verification_ops: 5,
    network_load_bp: 10_000,
    risk_bp: 1_500,
    market_domain: None,
    timestamp: Timestamp::new(1_000_000, 0),
};

let quote_record = quote(&policy, &inputs, "quote-1".into()).unwrap();
assert_eq!(quote_record.charged_amount_micro_exo, 0);
assert!(quote_record.zero_fee_reason.is_some());

let context = SettlementContext {
    receipt_id: "rec-1".into(),
    custody_transaction_hash: Hash256::from_bytes([0x33; 32]),
    prev_settlement_receipt: store.latest_receipt_hash(),
    now: Timestamp::new(1_010_000, 0),
};
let receipt = settle(&quote_record, &context, |_| Signature::from_bytes([7; 64])).unwrap();
assert_eq!(receipt.charged_amount_micro_exo, 0);

Re-exports

pub use adoption::ADOPTION_EVENT_HASH_DOMAIN;

pub use adoption::AdoptionEvent;

pub use adoption::USE_EVENT_HASH_DOMAIN;

pub use adoption::UseEvent;

pub use adoption::UseType;

pub use adoption::VALUE_EVENT_HASH_DOMAIN;

pub use adoption::ValueBasis;

pub use adoption::ValueEvent;

pub use bailment::BAILMENT_TERMS_HASH_DOMAIN;

pub use bailment::BAILMENT_WRAPPER_HASH_DOMAIN;

pub use bailment::BailmentTerms;

pub use bailment::BailmentWrapper;

pub use bailment::BailmentWrapperStatus;

pub use contribution_acceptance::AdopterType;

pub use contribution_acceptance::CONTRIBUTION_ACCEPTANCE_HASH_DOMAIN;

pub use contribution_acceptance::ContributionAcceptance;

pub use contribution_offer::CONTRIBUTION_OFFER_HASH_DOMAIN;

pub use contribution_offer::ContributionOffer;

pub use contribution_offer::ContributionOfferStatus;

pub use contribution_offer::ExpirationOrReview;

pub use contribution_offer::RequiredAuthorityLevel;

pub use contribution_receipt::ApprovalStatus;

pub use contribution_receipt::CONTRIBUTION_RECEIPT_HASH_DOMAIN;

pub use contribution_receipt::ContributionCategory;

pub use contribution_receipt::ContributionContributorType;

pub use contribution_receipt::ContributionReceipt;

pub use error::EconomyError;

pub use honorgood::apex_velocity_catalyst_client_services_mission;

pub use honorgood::apex_velocity_catalyst_client_services_ruleset;

pub use honorgood::apex_velocity_catalyst_software_channel_ruleset;

pub use honorgood::archon_exoforge_legacy_receipt;

pub use honorgood::archon_exoforge_ruleset;

pub use honorgood::paperclip_commandbase_legacy_receipt;

pub use honorgood::paperclip_commandbase_ruleset;

pub use honorgood::zero_launch_mission_settlement_reason;

pub use legacy::BeneficiaryRef;

pub use legacy::BeneficiaryType;

pub use legacy::LEGACY_RECEIPT_HASH_DOMAIN;

pub use legacy::LegacyReceipt;

pub use legacy::LegacyReceiptStatus;

pub use legacy::LegalEffect;

pub use legacy::MaterialityReview;

pub use legacy::MaterialityReviewStatus;

pub use legacy::MaterialityTier;

pub use mission::MISSION_HASH_DOMAIN;

pub use mission::Mission;

pub use mission::MissionPurpose;

pub use mission::MissionStatus;

pub use mission::MissionType;

pub use policy::ActorMultiplier;

pub use policy::AssuranceMultiplier;

pub use policy::ECONOMY_POLICY_HASH_DOMAIN;

pub use policy::EventMultiplier;

pub use policy::PricingPolicy;

pub use price::PriceBreakdown;

pub use price::PricingInputs;

pub use price::apply_bp;

pub use price::apply_multiplier;

pub use price::compute_breakdown;

pub use quote::ECONOMY_QUOTE_HASH_DOMAIN;

pub use quote::SettlementQuote;

pub use quote::quote;

pub use receipt::SETTLEMENT_RECEIPT_HASH_DOMAIN;

pub use receipt::SettlementReceipt;

pub use revenue_share::RevenueShareLine;

pub use revenue_share::RevenueShareTemplate;

pub use revenue_share::TemplateAllocation;

pub use revenue_share::distribute_revenue;

pub use ruleset::DurationPolicy;

pub use ruleset::HONOR_GOOD_RULESET_HASH_DOMAIN;

pub use ruleset::HonorGoodRuleset;

pub use ruleset::ReviewFrequency;

pub use ruleset::RulesetRecipientType;

pub use ruleset::RulesetScope;

pub use ruleset::RulesetShareLine;

pub use ruleset::RulesetStatus;

pub use ruleset::SettlementBasis;

pub use ruleset::validate_basis_allocations;

pub use settlement::AUTOMATED_SETTLEMENT_EVENT_HASH_DOMAIN;

pub use settlement::AutomatedSettlementEvent;

pub use settlement::AutomatedSettlementInputs;

pub use settlement::AutomatedSettlementRiskState;

pub use settlement::MISSION_SETTLEMENT_HASH_DOMAIN;

pub use settlement::MissionSettlement;

pub use settlement::SettlementContext;

pub use settlement::SettlementLine;

pub use settlement::checked_basis_point_amount;

pub use settlement::settle;

pub use settlement::settlement_lines_from_ruleset;

pub use store::ECONOMY_RECORD_ANCHOR_HASH_DOMAIN;

pub use store::EconomyObjectKind;

pub use store::EconomyRecordAnchor;

pub use store::EconomyStore;

pub use store::InMemoryEconomyStore;

pub use types::ActorClass;

pub use types::AssuranceClass;

pub use types::BasisPoints;

pub use types::DEFAULT_QUOTE_TTL_MS;

pub use types::EventClass;

pub use types::MAX_BASIS_POINTS;

pub use types::MAX_MULTIPLIER_BP;

pub use types::MicroExo;

pub use types::NEUTRAL_MULTIPLIER_BP;

pub use types::PricingMode;

pub use types::RevenueRecipient;

pub use types::ZeroFeeReason;

pub use value_contribution::AuthorityEnvelopeRef;

pub use value_contribution::ContributionType;

pub use value_contribution::ContributorType;

pub use value_contribution::ParticipantRef;

pub use value_contribution::VALUE_CONTRIBUTION_NODE_HASH_DOMAIN;

pub use value_contribution::ValueContributionNode;

pub use value_contribution::ValueContributionStatus;

Modules

adoption

Adoption, use, and value events for value-for-value settlement loops.

bailment

Bailment-style transactional wrappers for contribution adoption.

contribution_acceptance

Accepted contribution terms and delegated authority references.

contribution_offer

Contribution offers bind value nodes to terms and permitted use policy.

contribution_receipt

Mission and contribution workflow receipts.

error

Error types for the economy layer.

honorgood

Canonical HonorGood fixtures and Apex Velocity Catalyst policy templates.

legacy

Legacy receipts for evergreen provenance and conditional participation.

mission

Mission economics primitives.

policy

Pricing policy — bounded, integer-only, governance-versioned.

price

Pricing inputs and the deterministic, integer-only price formula.

quote

Settlement quotes — the bridge between pricing inputs and a settlement receipt. Every quote carries a deterministic hash so later settlement can prove the quote was unmodified.

receipt

Settlement receipts — signed, hash-chained records of a settled quote. Receipts exist for zero-priced settlements as well so trust is never paywalled.

revenue_share

Revenue share templates and per-quote allocation lines.

ruleset

HonorGood rulesets and deterministic share templates.

settlement

Settlement: build, sign, and chain a SettlementReceipt for a validated SettlementQuote.

store

Deterministic store for quotes, receipts, mission economics, and HonorGood value-contribution records.

types

Foundational economy types — actor classes, event classes, assurance classes, pricing modes, zero-fee reasons, and revenue-share recipient shapes. All values are integer-only; basis points are bounded.

value_contribution

Generalized value contribution nodes.

Constants

ECONOMY_DOMAINS

All economy hashing/signing domains. Used by hygiene tests and external auditors.