StellarTip API Reference

Source of truth: the doc comments on each method in src/lib.rs and the per-tier admin/registration/tipping sections below. This file is a curated, browsable summary; the per-method rustdoc in target/doc/stellar_tip/index.html (regenerated by CI) is the authoritative line-by-line reference.

Signatures: every public method takes env: Env as its first parameter and returns either () or a small return value. We omit env in the headings below to keep the per-method surface scannable; the full signature is in src/lib.rs and the per-page rustdoc HTML.

Lints: run cargo doc --no-deps --document-private-items=false (or make doc) to regenerate rustdoc locally. CI runs the same command and fails if rustdoc itself errors (broken intra-doc links, syntax errors in examples). New #![warn(missing_docs)] strictness is intentionally not enabled — public-facing surfaces are documented here and in rustdoc comments, but EVENT_* symbol constants are by design undocumented as a rustdoc concern (their meaning is fully captured in the Events table below).

Contract Information

Field	Value
Crate	`stellar-tip` (`v0.1.0`)
`crate-type`	`cdylib`
Soroban SDK	`=21.7.7` (pinned — see `Cargo.toml`)
Contract version	`3` (`get_contract_version()` returns `CONTRACT_VERSION`)
Currency semantics	Amounts are token base units (e.g. stroops for native XLM)

Errors

All methods return Result<(), TipError>-shaped errors via panic_with_error!. Error numbers (#N) are stable contract-level codes — they are part of the ABI and must not be renumbered.

Code (`#N`)	Variant	Triggered by
`#1`	`CreatorAlreadyExists`	`register()` — caller already has a profile.
`#2`	`CreatorNotFound`	`update_profile()` / `withdraw()` / `tip()` — no profile for caller/creator.
`#3`	`UsernameTaken`	`register()` — username already mapped.
`#4`	`InsufficientBalance`	`withdraw()` — balance < requested amount.
`#5`	`TransferFailed`	Underlying token contract call (e.g. SAC) reverts.
`#6`	`InvalidAmount`	`tip()` / `withdraw()` — non-positive `amount`.
`#7`	`NoTips`	Reserved — currently unreferenced; reserved for future "no history" cases.
`#8`	`NotInitialized`	`Admin` storage key absent (contract not `init()`-ed, or post-uninit).
`#9`	`AlreadyInitialized`	Re-invocation of `init()`.
`#10`	`Paused`	`register()`, `tip()`, `withdraw()` (and admin setters called via `check_initialized_and_not_paused`).
`#11`	`NotAuthorized`	Admin-only setter called by a non-admin.
`#12`	`InvalidInput`	Out-of-range parameters (`fee_bps > 10_000`, `min_tip_amount < 0`, banned admin or fee-recipient values, oversized strings).
`#13`	`BalanceNotEmpty`	`unregister()` — at least one token balance is non-zero.
`#14`	`CapExceeded`	`MaxCreators` or `MaxTipsPerCreator` reached.
`#15`	`FeeRecipientNotSet`	`tip()` — non-zero `fee_bps` but no `FeeRecipient` in storage.
`#16`	`BelowMinimum`	`tip()` — `amount` < configured `MinTipAmount` and `MinTipAmount > 0`.

Events

All state-changing methods publish exactly one event. Topics are (EVENT_*, ...). Payload types are listed in method tables below.

Symbol	Method(s)	Topic[1] (caller/admin)	Payload
`INIT`	`init`	caller (admin)	`(fee_recipient: Address, fee_bps: u32)`
`CREG`	`register`	caller (creator)	`(username: Symbol, registered_at: u64)`
`PUPD`	`update_profile`	caller	`(username: Symbol, display_name: String)`
`UREG`	`unregister`	caller	`()`
`TIP`	`tip`	`from`	`(creator, token, amount, fee, index)`
`WDRW`	`withdraw`	caller (creator)	`(token, amount)`
`PAUS`	`pause`	caller (admin)	`()`
`UNPA`	`unpause`	caller (admin)	`()`
`ADMC`	`set_admin`	previous admin	`new_admin: Address`
`FEEC`	`set_fee_percentage`	caller (admin)	`fee_bps: u32`
`FERC`	`set_fee_recipient`	caller (admin)	`fee_recipient: Address`
`CAPMC`	`set_max_creators`	caller (admin)	`max_creators: u32`
`CAPMT`	`set_max_tips_per_creator`	caller (admin)	`max_tips: u32`
`MINTC`	`set_min_tip_amount`	caller (admin)	`min_tip_amount: i128`

Admin Functions

All admin setters require caller.require_auth() and a match against DataKey::Admin. init() additionally validates input bounds and rejects a fee_recipient equal to the contract's own address.

`init(caller, fee_recipient, fee_bps, max_creators, max_tips_per_creator, min_tip_amount)`

Aspect	Detail
Brief	One-time initialization of admin, fee configuration, caps, and minimum tip.
Authorization	`caller` is recorded as admin.
Parameters	`caller: Address` · `fee_recipient: Address` (≠ contract) · `fee_bps: u32` (0–10 000) · `max_creators: u32` (`0`=unlimited) · `max_tips_per_creator: u32` (`0`=unlimited) · `min_tip_amount: i128` (`0`=disabled)
Returns	—
Errors	`#9` AlreadyInitialized · `#12` InvalidInput (out-of-range `fee_bps`, `min_tip_amount<0`, self-as-fee-recipient)
Event	`INIT`

Admin setters (all gated by caller == admin)

Method	Parameters	Notes / Errors	Event
`set_admin(caller, new_admin)`	new_admin: Address	Rejects `new_admin == caller` and the Stellar zero address → `#12`	`ADMC`
`pause(caller)`	—	No-op if already paused.	`PAUS`
`unpause(caller)`	—	No-op if already unpaused.	`UNPA`
`set_fee_percentage(caller, fee_bps)`	fee_bps: u32	Rejects `> 10_000` → `#12`.	`FEEC`
`set_fee_recipient(caller, addr)`	addr: Address	Rejects `addr == current_contract_address()` → `#12`.	`FERC`
`set_max_creators(caller, n)`	n: u32	Forward-only: does not retroactively evict creators when lowered.	`CAPMC`
`set_max_tips_per_creator(caller, n)`	n: u32	Forward-only: existing tip history is preserved when cap is lowered.	`CAPMT`
`set_min_tip_amount(caller, min)`	min: i128	Rejects `min < 0` → `#12`. Raising does not invalidate existing tips.	`MINTC`

Registration

`register(env, caller, username, display_name, bio)`

Aspect	Detail
Brief	Register a unique creator profile. Pauses block this call.
Authorization	`caller.require_auth()`
Parameters	`caller: Address` · `username: Symbol` (≤ 32 bytes via `ScSymbol`) · `display_name: String` (≤ 64 bytes) · `bio: String` (≤ 256 bytes)
Returns	—
Errors	`#10` Paused · `#1` CreatorAlreadyExists · `#3` UsernameTaken · `#14` CapExceeded · `#12` InvalidInput (oversized strings)
Event	`CREG`

`update_profile(env, caller, display_name, bio)`

Aspect	Detail
Brief	Update the caller's display_name and bio.
Authorization	`caller.require_auth()`
Parameters	`caller: Address` · `display_name: String` (≤ 64) · `bio: String` (≤ 256)
Returns	—
Errors	`#10` Paused · `#2` CreatorNotFound · `#12` InvalidInput
Event	`PUPD`

`unregister(env, caller)`

Aspect	Detail
Brief	Tear down the caller's profile and clear username-mapping; requires zero across all token balances.
Authorization	`caller.require_auth()`
Parameters	`caller: Address`
Returns	—
Errors	`#10` Paused · `#2` CreatorNotFound · `#13` BalanceNotEmpty
Event	`UREG`
Side effects	Removes `Profile(caller)`, `UsernameToAddress(username)`, `TipCount(caller)`, all `Balance(caller, _)` entries, and the `CreatorTokens(caller)` set. Decrements `CreatorCount`.

Tipping

`tip(from, creator, token, amount, message)`

Aspect	Detail
Brief	Move `amount` of `token` from `from` into the contract; credit the creator; record history.
Authorization	`from.require_auth()`
Parameters	`from: Address` · `creator: Address` (must be registered) · `token: Address` · `amount: i128` (> `MinTipAmount` when `MinTipAmount > 0`) · `message: String`
Returns	`u64` — the new tip index (`TipCount` value before increment).
Errors	`#10` Paused · `#8`/`#6`/`#16` flow-related · `#2` CreatorNotFound · `#14` CapExceeded (tip cap reached) · `#15` FeeRecipientNotSet (non-zero `fee_bps` but no recipient) · `#5` TransferFailed
Event	`TIP`
Fee math	`fee = (amount * fee_bps) / 10_000`; `creator_amount = amount - fee`.

Withdrawal

`withdraw(env, caller, token, amount)`

Aspect	Detail
Brief	Send `amount` of `token` from this contract to `caller`. The internal balance is decremented atomically; tracking keys are pruned when the balance reaches zero.
Authorization	`caller.require_auth()`
Parameters	`caller: Address` (must be a registered creator) · `token: Address` · `amount: i128` (> 0)
Returns	—
Errors	`#10` Paused · `#2` CreatorNotFound · `#6` InvalidAmount · `#4` InsufficientBalance · `#5` TransferFailed
Event	`WDRW`

View Functions

All view functions are read-only, return options/zero-defaults for missing storage, and never emit events. None are gated by require_auth.

Profiles

Method	Returns
`get_profile(env, address) -> Option<CreatorProfile>`	`None` if not registered.
`get_creator_from_username(env, username) -> Option<Address>`	`None` if username is free.
`get_profile_by_username(env, username) -> Option<CreatorProfile>`	Convenience composition of the two above.
`is_creator(env, address) -> bool`	`true` iff a `Profile` key exists for `address`.
`is_username_taken(env, username) -> bool`	`true` iff the username has been mapped.

Balances & History

Method	Returns
`get_balance(env, creator, token) -> i128`	Creator's internal balance; `0` if absent.
`get_tip_count(env, creator) -> u64`	Tip history length (`TipCount` value); `0` if the key is absent.
`get_tip(env, creator, index) -> Option<Tip>`	`None` if the index is out of range.
`get_tips(env, creator, start, limit) -> Vec<Tip>`	Paginated slice of tip history; `end = min(start+limit, tip_count)`.
`get_all_tokens(env, creator) -> Vec<Address>`	All tokens the creator has received tips in (`Map<Address, ()>` flattened to keys).

Configuration

Method	Returns
`get_contract_version() -> u32`	Currently `3`.
`get_admin() -> Option<Address>`	`None` if `init()` has not run.
`is_paused() -> bool`	Defaults to `false`.
`get_fee_percentage() -> u32`	Current basis points; default `0`.
`get_fee_recipient() -> Option<Address>`	`None` when unset.
`get_max_creators() -> u32`	`0` means the cap is disabled (unlimited).
`get_max_tips_per_creator() -> u32`	`0` means the cap is disabled (unlimited).
`get_min_tip_amount() -> i128`	`0` means the minimum is disabled.
`get_creator_count() -> u32`	Tracked alongside `MaxCreators` so cap enforcement is O(1).

Type Summary

`DataKey` (storage key enum)

Defined as a #[contracttype] enum and used as the key for instance/persistent storage. Public to callers only as a return type of view functions that re-expose storage; never directly caller-supplied.

`CreatorProfile`

pub struct CreatorProfile {
    pub username: Symbol,
    pub display_name: String,
    pub bio: String,
    pub registered_at: u64,
}

`Tip`

pub struct Tip {
    pub from: Address,
    pub token: Address,
    pub amount: i128,
    pub message: String,
    pub timestamp: u64,
}

Constants

Constant	Value	Notes
`CONTRACT_VERSION`	`3`	Bump on backwards-incompatible WASM shape changes.
`MAX_FEE_BPS`	`10_000`	100% in basis points; admin setters reject anything larger.
`MAX_DISPLAY_NAME_LEN`	`64` bytes	Enforced in `register()` / `update_profile()` via `validate_input`.
`MAX_BIO_LEN`	`256` bytes	Same.
`DEFAULT_MAX_CREATORS`	`10_000`	Used by `init()` default tests; can be overridden explicitly.
`DEFAULT_MAX_TIPS_PER_CREATOR`	`10_000`	Same.
`DEFAULT_MIN_TIP_AMOUNT`	`1`	Equivalent to the prior `amount > 0` guard; raise post-deploy.
`TTL_THRESHOLD` / `TTL_EXTEND`	15 / 30 days (ledgers)	Internal — applied through `extend_instance_ttl` / `extend_persistent_ttl`.

Regenerating This Reference

# Regenerate HTML rustdoc under target/doc/ (CI does the same)
make doc

# Or directly:
cargo doc --no-deps --document-private-items=false

The HTML tree at target/doc/stellar_tip/index.html is the canonical line-by-line API reference. This markdown file is the curated, browsable overview and is the one to update when adding or removing public methods.

FilesExpand file tree

API_REFERENCE.md

Latest commit

History