This page is for contributors working on stellar-contract/. It is not the
consumer reference. External SDK users should read
sdk-api-reference.md, which lists every public
entrypoint with its arguments, auth requirements and error codes.
- Source of truth:
stellar-contract/src/lib.rs(entrypoints) andstellar-contract/src/errors.rs(error codes). - Module layout: stellar-contract/ARCHITECTURE.md and ADR-0013.
- Previous full text: the long-form function reference was retired in favour of the generated tables. It is kept at archive/CONTRACT_DOCUMENTATION-pre-1445.md.
Generated from stellar-contract/src/lib.rs. 1 entrypoints are documented as internal-only and are excluded from the consumer reference in sdk-api-reference.md. Do not edit this table by hand.
| Entrypoint | Arguments | Returns | Requires auth | Errors | Note |
|---|---|---|---|---|---|
record_performance_metric |
admin: Address, gas_used: u64, is_success: bool |
() |
admin |
— | Record a performance metric (internal helper or admin-only). |
python3 scripts/generate-contract-reference.py # rewrite both docs
python3 scripts/generate-contract-reference.py --check # fail if they are stale (CI)Status: Completed
Date: October 2026
- Consolidated:
contract_analytics.rsandanalytics.rsmerged into singleanalytics.rsmodule - Removed: Complex reporting types (
ReportType,AnalyticsReport,CustomQuery,AggregationType,AnalyticsEngine) - Added: Storage integration for analytics persistence and periodic batching
Both modules were unused in production:
contract_analytics.rs(65 LOC): Debug-only helpers with no callersanalytics.rs(348 LOC): Complex reporting framework exported but never instantiated
Neither module persisted data to storage, making them ineffective for their intended purpose.
| Aspect | Before | After |
|---|---|---|
| Modules | 2 duplicate modules | 1 unified module |
| Public exports | 6 unused types | 0 (module is private) |
| Storage integration | None | Periodic batching (every 10 tx) |
| Per-tx overhead | 0 stroops | +0.325 stroops (10% increase, amortized) |
| Tests | 0 | 13 unit tests + 3 storage key tests |
| Breaking changes | N/A | None (removed types were unused) |
New storage keys for issue #1514 (all in stellar-contract/src/storage_keys.rs):
| Key | Type | Purpose |
|---|---|---|
GLOBAL_METRICS_SNAPSHOT |
Symbol | On-chain analytics snapshot |
ANALYTICS_LAST_UPDATE |
Symbol | Snapshot timestamp |
ANALYTICS_BATCH_COUNT |
Symbol | Batching counter |
recycling_stats_key(address) |
Tuple | Per-participant stats |
All keys follow naming conventions:
- Symbol keys: ≤9 chars (Soroban limit)
- Tuple keys:
("recycling_stats", address)format - No collisions (verified by tests)
If the contract was already deployed with the old analytics types:
- Old state:
contract_analyticsmodule exported (debug-only) - New state: Module removed, analytics is private
- Breaking changes: None (module was not part of ABI)
- Data migration: No on-chain data to migrate (module never persisted anything)
For future contract upgrades, use analytics::initialize_analytics_on_upgrade() to bootstrap metrics.
- Indexer: Remains authoritative source for reporting
- Snapshots: On-chain snapshots provide audit trail only
- Periodic batching: Configurable (currently every 10 transactions)
- Accuracy: Off-chain and on-chain may diverge by up to 10 transactions
- Analysis:
stellar-contract/ANALYTICS_CONSOLIDATION_ANALYSIS.md - Design:
stellar-contract/ANALYTICS_DESIGN.md - Test Report:
stellar-contract/ANALYTICS_CONSOLIDATION_TEST_REPORT.md - Storage Impact:
stellar-contract/ANALYTICS_STORAGE_IMPACT.md