contract-api.md

Contract API — marketplace-escrow

Soroban SDK 22. Testnet deployment: CDRJORPUFXD54OEE4ZIMYN7WPXZCRVYPO7F5UCRT4SNSKMT5PPIBGK36 (1% fee).

Construction

__constructor(fee_collector: Address, fee_bps: u32) — set once at deploy time. fee_bps is capped at 1000 (10%); the live deployment uses 100 (1%).

Types

Listing

Field	Type	Notes
id	u64	Monotonic id at creation.
seller	Address	Listed the item.
buyer	Option<Address>	Set on order.
token	Address	SEP-41 payment token.
price	i128	Price in escrow (smallest unit).
status	ListingStatus	Listed/Ordered/Delivered/Completed/Cancelled.
metadata	String	Off-chain pointer (≤ 512 bytes).
created_at	u64	Ledger timestamp.
deadline	u64	Unix seconds; 0 = none.

Config

{ fee_collector: Address, fee_bps: u32 }

Mutating functions

Function	Auth	Pre-state	Effect
create_listing(seller, token, price, deadline, metadata) -> u64	seller	—	Creates a listing (no escrow yet).
order(listing_id, buyer)	buyer	Listed	Locks price in escrow; → Ordered.
deliver(listing_id)	seller	Ordered	→ Delivered.
confirm(listing_id)	buyer	Delivered	Releases price − fee to seller, fee to collector; → Completed.
cancel_listing(listing_id)	seller	Listed	→ Cancelled (no funds moved).
refund_expired(listing_id)	buyer	Ordered & past deadline	Refunds buyer; → Cancelled.

Read-only views

Function	Returns
get_listing(listing_id) -> Listing	A single listing.
listing_count() -> u64	Total listed (next id).
get_config() -> Config	Fee collector + bps.
list_listings(start, limit) -> Vec<Listing>	Page (limit capped at 100).

Errors

Code	Name	Meaning
1	AlreadyInitialized	Constructor called twice.
2	ListingNotFound	No listing with that id.
3	Unauthorized	Caller not allowed / config missing.
4	InvalidStatus	Wrong state for this transition.
5	InvalidPrice	Price must be > 0.
6	InvalidFee	fee_bps > 1000.
7	InvalidDeadline	Deadline in the past.
8	MetadataTooLong	Metadata > 512 bytes.
9	NoBuyer	Operation needs a buyer.
10	DeadlineNotReached	Cannot refund before the deadline.
11	NoDeadline	Order has no deadline to expire.

Events

Topic	Data
listed, id	(seller, price)
ordered, id	buyer
delivered, id	seller
completed, id	(seller, seller_amount, fee)
cancelled, id	seller
refunded, id	buyer