Skip to content

Commit e0c4a45

Browse files
greatest0fallt1megreatest0fallt1me
authored
Merge pull request #208 from armandocodecr/docs/contract-interface-summaries
docs: contract interface summaries for integrators
2 parents 48933a5 + c7ae410 commit e0c4a45

File tree

7 files changed

+822
-6
lines changed

7 files changed

+822
-6
lines changed

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,13 +124,28 @@ callora-contracts/
124124
├── scripts/
125125
│ ├── coverage.sh # Local coverage runner
126126
│ └── check-wasm-size.sh # WASM size verification
127+
├── docs/
128+
│ ├── interfaces/ # JSON contract interface summaries (vault, settlement, revenue_pool)
129+
│ └── ACCESS_CONTROL.md # Role-based access control overview
127130
├── BENCHMARKS.md # Gas/cost notes
128131
├── EVENT_SCHEMA.md # Event topics and payloads
129132
├── UPGRADE.md # Upgrade and migration path
130133
├── SECURITY.md # Security checklist
131134
└── tarpaulin.toml # cargo-tarpaulin configuration
132135
```
133136

137+
## Contract interface summaries
138+
139+
Machine-readable JSON summaries of every public function and parameter for each contract are maintained under [`docs/interfaces/`](docs/interfaces/). They serve as the canonical reference for backend integrators using `@stellar/stellar-sdk`.
140+
141+
| File | Contract |
142+
|------|----------|
143+
| [`docs/interfaces/vault.json`](docs/interfaces/vault.json) | `callora-vault` |
144+
| [`docs/interfaces/settlement.json`](docs/interfaces/settlement.json) | `callora-settlement` |
145+
| [`docs/interfaces/revenue_pool.json`](docs/interfaces/revenue_pool.json) | `callora-revenue-pool` |
146+
147+
See [`docs/interfaces/README.md`](docs/interfaces/README.md) for the schema description and regeneration steps.
148+
134149
## Security Notes
135150

136151
- **Checked arithmetic**: All mutations use `checked_add` / `checked_sub`.

‎contracts/settlement/src/test_views.rs‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
#![cfg(test)]
2-
31
use crate::{CalloraSettlement, CalloraSettlementClient};
42
use soroban_sdk::{testutils::Address as _, Address, Env};
53

‎contracts/vault/src/lib.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,6 @@ pub enum StorageKey {
8282
DepositorList,
8383
}
8484

85-
// Replaced by StorageKey enum variants
86-
8785
/// Default maximum single deduct amount when not set at init (no cap).
8886
pub const DEFAULT_MAX_DEDUCT: i128 = i128::MAX;
8987
/// Maximum number of items allowed in a single batch_deduct call.
@@ -95,6 +93,9 @@ pub const MAX_BATCH_SIZE: u32 = 50;
9593
/// Storage key for allowed depositors list.
9694
pub const ALLOWED_KEY: &str = "allowed_depositors";
9795

96+
/// Maximum number of items allowed in a single batch_deduct call.
97+
pub const MAX_BATCH_SIZE: u32 = 50;
98+
9899
/// Maximum length for offering metadata (e.g. IPFS CID or URI).
99100
pub const MAX_METADATA_LEN: u32 = 256;
100101
/// Maximum length for offering IDs.

‎contracts/vault/src/test_init_hardening.rs‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
#![cfg(test)]
2-
31
use crate::{CalloraVault, CalloraVaultClient};
42
use soroban_sdk::{testutils::Address as _, Address, Env};
53

‎docs/interfaces/revenue_pool.json‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
{
2+
"contract": "callora-revenue-pool",
3+
"version": "0.0.1",
4+
"description": "Simple revenue distribution contract. Receives USDC when the vault forwards deducted funds and lets the admin distribute those funds to developer wallets individually or in batch.",
5+
"crate": "callora-revenue-pool",
6+
"source": "contracts/revenue_pool/src/lib.rs",
7+
8+
"types": {},
9+
10+
"functions": [
11+
{
12+
"name": "init",
13+
"description": "Initialize the revenue pool with an admin and the USDC token address. Can only be called once. The admin must authorize the call.",
14+
"access": "admin (must sign)",
15+
"params": [
16+
{ "name": "admin", "type": "Address", "optional": false, "description": "Address that may call distribute, batch_distribute, receive_payment, and set_admin." },
17+
{ "name": "usdc_token", "type": "Address", "optional": false, "description": "Stellar USDC (or wrapped USDC) token contract address." }
18+
],
19+
"returns": "void",
20+
"panics": [
21+
"\"revenue pool already initialized\" — called more than once."
22+
],
23+
"events": [
24+
{ "topics": ["\"init\"", "admin"], "data": "usdc_token (Address)" }
25+
]
26+
},
27+
28+
{
29+
"name": "distribute",
30+
"description": "Transfer USDC from this contract to a developer wallet. Admin only.",
31+
"access": "admin",
32+
"params": [
33+
{ "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
34+
{ "name": "to", "type": "Address", "optional": false, "description": "Developer address to receive USDC." },
35+
{ "name": "amount", "type": "i128", "optional": false, "description": "Amount in USDC base units; must be > 0." }
36+
],
37+
"returns": "void",
38+
"panics": [
39+
"\"unauthorized: caller is not admin\" — caller != current admin.",
40+
"\"amount must be positive\" — amount <= 0.",
41+
"\"revenue pool not initialized\" — called before init.",
42+
"\"insufficient USDC balance\" — contract holds less than amount."
43+
],
44+
"events": [
45+
{ "topics": ["\"distribute\"", "to"], "data": "amount (i128)" }
46+
]
47+
},
48+
49+
{
50+
"name": "batch_distribute",
51+
"description": "Atomically distribute USDC to multiple developer wallets. Validates the total against the available balance before any transfer. One event is emitted per payment. Admin only.",
52+
"access": "admin",
53+
"params": [
54+
{ "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
55+
{ "name": "payments", "type": "Vec<(Address, i128)>", "optional": false, "description": "Ordered list of (developer_address, amount) pairs. All amounts must be > 0." }
56+
],
57+
"returns": "void",
58+
"panics": [
59+
"\"unauthorized: caller is not admin\" — caller != current admin.",
60+
"\"amount must be positive\" — any individual amount <= 0.",
61+
"\"total overflow\" — extremely unlikely sum overflow.",
62+
"\"revenue pool not initialized\" — called before init.",
63+
"\"insufficient USDC balance\" — total amount exceeds contract balance."
64+
],
65+
"events": [
66+
{ "note": "One event per payment entry.", "topics": ["\"batch_distribute\"", "to"], "data": "amount (i128)" }
67+
]
68+
},
69+
70+
{
71+
"name": "receive_payment",
72+
"description": "Event-only helper — does NOT move tokens. Emits a receive_payment event for indexer alignment when the backend wants to log a payment credited from the vault. USDC is received passively when any address transfers tokens to this contract; no explicit call is required for token receipt.",
73+
"access": "admin",
74+
"params": [
75+
{ "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
76+
{ "name": "amount", "type": "i128", "optional": false, "description": "Amount received (for event logging only; no tokens are moved)." },
77+
{ "name": "from_vault", "type": "bool", "optional": false, "description": "True if the source was the vault contract." }
78+
],
79+
"returns": "void",
80+
"panics": [
81+
"\"unauthorized: caller is not admin\" — caller != current admin."
82+
],
83+
"events": [
84+
{ "topics": ["\"receive_payment\"", "caller"], "data": "(amount, from_vault) tuple" }
85+
]
86+
},
87+
88+
{
89+
"name": "balance",
90+
"description": "Return the contract's current USDC balance.",
91+
"access": "any",
92+
"params": [],
93+
"returns": "i128",
94+
"panics": [
95+
"\"revenue pool not initialized\" — called before init."
96+
],
97+
"events": []
98+
},
99+
100+
{
101+
"name": "get_admin",
102+
"description": "Return the current admin address.",
103+
"access": "any",
104+
"params": [],
105+
"returns": "Address",
106+
"panics": [
107+
"\"revenue pool not initialized\" — called before init."
108+
],
109+
"events": []
110+
},
111+
112+
{
113+
"name": "set_admin",
114+
"description": "Initiate replacement of the current admin. The proposed new admin must call claim_admin to complete the transfer.",
115+
"access": "admin",
116+
"params": [
117+
{ "name": "caller", "type": "Address", "optional": false, "description": "Must be the current admin; must authorize." },
118+
{ "name": "new_admin", "type": "Address", "optional": false, "description": "Address of the proposed new admin." }
119+
],
120+
"returns": "void",
121+
"panics": [
122+
"\"unauthorized: caller is not admin\" — caller != current admin."
123+
],
124+
"events": [
125+
{ "topics": ["\"admin_transfer_started\"", "current_admin"], "data": "new_admin (Address)" }
126+
]
127+
},
128+
129+
{
130+
"name": "claim_admin",
131+
"description": "Complete the admin transfer. Must be called by the pending admin set via set_admin.",
132+
"access": "pending admin (must sign)",
133+
"params": [
134+
{ "name": "caller", "type": "Address", "optional": false, "description": "Must be the pending admin; must authorize." }
135+
],
136+
"returns": "void",
137+
"panics": [
138+
"\"no pending admin\" — set_admin was not called first.",
139+
"\"unauthorized: caller is not pending admin\" — caller is not the pending admin."
140+
],
141+
"events": [
142+
{ "topics": ["\"admin_transfer_completed\"", "new_admin"], "data": "void" }
143+
]
144+
}
145+
]
146+
}

0 commit comments

Comments
 (0)