Buys a listed (already-minted) token in a single invocation: payment
out, token in. payment_token selects which of the listing's prices
to pay — must be one the seller actually offered.
Only the buyer signs. The seller's consent was given when they created
the listing, and the token moves via [Consecutive::update] (the
low-level, no-auth path) rather than a full transfer, which would
demand the seller's signature at purchase time.
fn buy(
env: soroban_sdk::Env,
buyer: soroban_sdk::Address,
token_id: u32,
payment_token: soroban_sdk::Address,
inclusion_fee: i128,
network_fee: i128,
)Destroys the token with token_id from from.
e - Access to the Soroban environment.from - The account whose token is destroyed.token_id - The identifier of the token to burn.crate::non_fungible::NonFungibleTokenError::NonExistentToken] -
When attempting to burn a token that does not exist.crate::non_fungible::NonFungibleTokenError::IncorrectOwner] - If
the current owner (before calling this function) is not from.["burn", from: Address][token_id: u32]fn burn(env: soroban_sdk::Env, from: soroban_sdk::Address, token_id: u32)Lists the caller's token for sale in one or more currencies, same
shape as an edition's own price grid — a reseller isn't limited to
whichever currencies the creator originally offered. Listing does not
escrow the token — the owner keeps it and can still transfer or burn
it, which is why buy re-checks ownership rather than trusting the
stored seller.
fn list(
env: soroban_sdk::Env,
seller: soroban_sdk::Address,
token_id: u32,
prices: soroban_sdk::Vec,
) Returns the token collection name.
e - Access to the Soroban environment.fn name(env: soroban_sdk::Env) -> soroban_sdk::StringEmergency stop for buy_edition, list, buy, and
unlock_token_for. Transfers, approvals, and cancel_listing stay
open so holders can always exit a position while the platform is
halted.
fn pause(env: soroban_sdk::Env, caller: soroban_sdk::Address)Returns true if the contract is paused, and false otherwise.
e - Access to Soroban environment.fn paused(env: soroban_sdk::Env) -> boolReturns the token collection symbol.
e - Access to the Soroban environment.fn symbol(env: soroban_sdk::Env) -> soroban_sdk::StringGives permission to approved to transfer the token with token_id to
another account. The approval is cleared when the token is
transferred.
Only a single account can be approved at a time for a token_id.
To remove an approval, the approver can approve their own address,
effectively removing the previous approved address. Alternatively,
setting the live_until_ledger to 0 will also revoke the approval.
e - Access to Soroban environment.approver - The address of the approver (should be owner or
operator).approved - The address receiving the approval.token_id - Token ID as a number.live_until_ledger - The ledger number at which the allowance
expires. If live_until_ledger is 0, the approval is revoked.NonFungibleTokenError::NonExistentToken] - If the token does not
exist.NonFungibleTokenError::InvalidApprover] - If the owner address is
not the actual owner of the token.NonFungibleTokenError::InvalidLiveUntilLedger] - If the ledgefn approve(
env: soroban_sdk::Env,
approver: soroban_sdk::Address,
approved: soroban_sdk::Address,
token_id: u32,
live_until_ledger: u32,
)Returns the number of tokens owned by account.
e - Access to the Soroban environment.account - The address for which the balance is being queried.fn balance(env: soroban_sdk::Env, account: soroban_sdk::Address) -> u32fn listing(env: soroban_sdk::Env, token_id: u32) -> Optionfn unpause(env: soroban_sdk::Env, caller: soroban_sdk::Address)Replaces this contract's executable code in place — same address,
same storage, so the platform can ship behavior changes (or fix a
bug) without a redeploy and without anyone needing to be pointed at a
new contract id. #[only_owner] ignores whatever address is passed
as _operator and enforces the real owner from storage instead — see
stellar-macros' docs on the macro.
fn upgrade(
env: soroban_sdk::Env,
new_wasm_hash: soroban_sdk::BytesN<32>,
operator: soroban_sdk::Address,
)The contract build currently running on-chain — bump
CONTRACT_VERSION on every release that changes behavior so this
stays truthful after an upgrade.
fn version(env: soroban_sdk::Env) -> u32Synthesizes a single token's metadata from the edition it was minted from — editions store their descriptive fields once, not once per copy, so this is an indirection rather than a direct read.
fn art_meta(env: soroban_sdk::Env, token_id: u32) -> OptionReturns the owner of the token with token_id.
e - Access to the Soroban environment.token_id - Token ID as a number.NonFungibleTokenError::NonExistentToken] - If the token does not
exist.fn owner_of(env: soroban_sdk::Env, token_id: u32) -> soroban_sdk::AddressTransfers the token with token_id from from to to.
WARNING: Confirmation that the recipient is capable of receiving the
Non-Fungible is the caller's responsibility; otherwise the NFT may be
permanently lost.
e - Access to the Soroban environment.from - Account of the sender.to - Account of the recipient.token_id - Token ID as a number.NonFungibleTokenError::IncorrectOwner] - If the current owner
(before calling this function) is not from.NonFungibleTokenError::NonExistentToken] - If the token does not
exist.["transfer", from: Address, to: Address][token_id: u32]fn transfer(
env: soroban_sdk::Env,
from: soroban_sdk::Address,
to: soroban_sdk::Address,
token_id: u32,
)fn treasury(env: soroban_sdk::Env) -> OptionDestroys the token with token_id from from, by using spenders
approval.
e - Access to the Soroban environment.spender - The account that is allowed to burn the token on behalf of
the owner.from - The account whose token is destroyed.token_id - The identifier of the token to burn.crate::non_fungible::NonFungibleTokenError::NonExistentToken] -
When attempting to burn a token that does not exist.crate::non_fungible::NonFungibleTokenError::IncorrectOwner] - If
the current owner (before calling this function) is not from.crate::non_fungible::NonFungibleTokenError::InsufficientApproval] -
If the spender does not have a valid approval.["burn", from: Address][token_id: u32]fn burn_from(
env: soroban_sdk::Env,
spender: soroban_sdk::Address,
from: soroban_sdk::Address,
token_id: u32,
)Buys several listed tokens at once, all paid in the same currency —
one signature instead of one buy call per token. The common case:
a buyer picking N copies pooled across one or more resale listings
for the same edition. Listings can belong to different sellers; each
token still settles (payment split, ownership transfer, Purchased
event) exactly as an individual buy would, just in one invocation.
inclusion_fee/network_fee are charged once for the whole batch
(there's only one real Soroban transaction underneath, regardless of
how many tokens it settles), not once per token — capped against the
sum of every token's own price, computed up front in a read-only
pass before any listing is touched.
fn buy_batch(
env: soroban_sdk::Env,
buyer: soroban_sdk::Address,
token_ids: soroban_sdk::Vec,
payment_token: soroban_sdk::Address,
inclusion_fee: i128,
network_fee: i128,
) Returns Some(Address) if ownership is set, or None if ownership has
been renounced.
e - Access to the Soroban environment.fn get_owner(env: soroban_sdk::Env) -> OptionReturns the Uniform Resource Identifier (URI) for the token with
token_id.
e - Access to the Soroban environment.token_id - Token ID as a number.If the token does not exist, this function is expected to panic.
fn token_uri(env: soroban_sdk::Env, token_id: u32) -> soroban_sdk::StringRefreshes this contract's own TTL, plus the Edition/EditionPrices
entries for every id in edition_ids and the ownership data for
every id in token_ids. Permissionless (no require_auth at all) —
it only ever extends TTLs, never reads a balance, moves a token, or
touches payment, so there's nothing here for an untrusted caller to
abuse; anyone (typically a scheduled off-chain job) can pay to keep
the collection warm.
An edition_ids entry that doesn't resolve to anything (never
registered, wrong id) is silently skipped. token_ids entries are
not — same as everywhere else Consecutive::owner_of is called in
this contract, an id that was never minted or was since burned
panics the whole call, so callers (the off-chain scheduler) should
only pass ids their own records show as actually minted.
fn keep_alive(
env: soroban_sdk::Env,
edition_ids: soroban_sdk::Vec,
token_ids: soroban_sdk::Vec,
) Lists several of the caller's tokens at once, all at the same price
grid — one signature instead of one list call per token. The common
case: a seller holding a consecutive run from one buy_edition
purchase relists several of them together. Each token still gets its
own independent Listing entry (and its own Listed event, via
do_list) — this is purely a batching of the same per-token effect
list has, not a new pooled-listing concept.
fn list_batch(
env: soroban_sdk::Env,
seller: soroban_sdk::Address,
token_ids: soroban_sdk::Vec,
prices: soroban_sdk::Vec,
) Buys quantity copies of an edition, minting them straight to
buyer in the same call that takes payment.
The first purchase of a given edition_ref also registers the
edition from edition — every later purchase of the same ref ignores
edition entirely and just mints the next range against the already-
registered data. This is why the creator never has to sign anything
to "list": edition's fields are backend-supplied from the trusted
database row (the same trust model mint_and_list used to build its
XDR server-side under), and EditionByRef dedup means only that first
call can ever set them — nothing here requires the creator's
authorization, only the buyer's.
purchase_ref is the caller's own identifier for this purchase
attempt (a fresh id per attempt, not per edition). It's recorded so
the minted range can be looked up afterwards with
[Self::purchase_by_ref] — this repo's pinned stellar-sdk cannot
decode protocol-27 transaction meta, so neither the return value nor
emitted events
fn buy_edition(
env: soroban_sdk::Env,
buyer: soroban_sdk::Address,
edition_ref: soroban_sdk::String,
edition: EditionInput,
purchase_ref: soroban_sdk::String,
payment_token: soroban_sdk::Address,
quantity: u32,
inclusion_fee: i128,
network_fee: i128,
) -> (u32, u32)fn edition_meta(env: soroban_sdk::Env, edition_id: u32) -> OptionReturns the account approved for the token with token_id.
e - Access to the Soroban environment.token_id - Token ID as a number.NonFungibleTokenError::NonExistentToken] - If the token does not
exist.fn get_approved(env: soroban_sdk::Env, token_id: u32) -> OptionERC2981-shaped royalty lookup, resolved from the token's edition
rather than the OZ royalties extension's own storage — see the doc
comment in buy_edition for why. A token with no edition (shouldn't
happen for anything this contract minted) reports no royalty rather
than panicking, matching the OZ default's own "nothing set" behavior.
fn royalty_info(
env: soroban_sdk::Env,
token_id: u32,
sale_price: i128,
) -> (soroban_sdk::Address, i128)Runs exactly once, at deploy. Using a constructor rather than an
initialize entry point means there is no window in which an
uninitialized contract can be claimed by whoever calls first.
fn __constructor(
env: soroban_sdk::Env,
owner: soroban_sdk::Address,
treasury: soroban_sdk::Address,
platform_fee_bps: u32,
name: soroban_sdk::String,
symbol: soroban_sdk::String,
base_uri: soroban_sdk::String,
unlock_authority: soroban_sdk::Address,
)Transfers the token with token_id from from to to by using
spenders approval.
Unlike transfer(), which is used when the token owner initiates the
transfer, transfer_from() allows an approved third party
(spender) to transfer the token on behalf of the owner. This
function verifies that spender has the necessary approval.
WARNING: Confirmation that the recipient is capable of receiving the
Non-Fungible is the caller's responsibility; otherwise the NFT may be
permanently lost.
e - Access to the Soroban environment.spender - The address authorizing the transfer.from - Account of the sender.to - Account of the recipient.token_id - Token ID as a number.NonFungibleTokenError::IncorrectOwner] - If the current owner
(before calling this function) is not from.NonFungibleTokenError::InsufficientApproval] - If the spender does
not have a valid approval.NonFungibleTokenError::NonExistentToken] - If the token does not
exist.fn transfer_from(
env: soroban_sdk::Env,
spender: soroban_sdk::Address,
from: soroban_sdk::Address,
to: soroban_sdk::Address,
token_id: u32,
)fn cancel_listing(env: soroban_sdk::Env, seller: soroban_sdk::Address, token_id: u32)Resolves the caller's off-chain reference back to the registered edition id. This is how the backend confirms an edition exists on-chain and learns its id after the first purchase.
fn edition_by_ref(
env: soroban_sdk::Env,
edition_ref: soroban_sdk::String,
) -> Optionfn edition_prices(
env: soroban_sdk::Env,
edition_id: u32,
) -> soroban_sdk::VecRead-only preview of buy's payment split for one of the listing's
currencies, so the UI can show the buyer exactly where their money
goes before they sign.
fn sale_breakdown(
env: soroban_sdk::Env,
token_id: u32,
payment_token: soroban_sdk::Address,
) -> OptionRewrites an already-registered edition's title/description/
thumbnail/supply/prices. media_url, media_type, creator, and
royalty_bps are deliberately not parameters — they're read
from the existing EditionMeta and carried over untouched, so
there's no path, accidental or otherwise, that can alter them.
supply can only move down to meta.minted and never above the
edition's current supply — never diluting what existing holders
already bought into, never letting already-minted copies exceed
their own edition's cap.
fn update_edition(
env: soroban_sdk::Env,
caller: soroban_sdk::Address,
edition_id: u32,
title: soroban_sdk::String,
description: soroban_sdk::String,
thumbnail_url: soroban_sdk::String,
supply: u32,
prices: soroban_sdk::Vec,
) Approve or remove operator as an operator for the owner.
Operators can call transfer_from() for any token held by owner,
and call approve() on behalf of owner.
e - Access to Soroban environment.owner - The address holding the tokens.operator - Account to add to the set of authorized operators.live_until_ledger - The ledger number at which the allowance
expires. If live_until_ledger is 0, the approval is revoked.NonFungibleTokenError::InvalidLiveUntilLedger] - If the ledger
number is less than the current ledger number.["approve_for_all", from: Address][operator: Address, live_until_ledger: u32]fn approve_for_all(
env: soroban_sdk::Env,
owner: soroban_sdk::Address,
operator: soroban_sdk::Address,
live_until_ledger: u32,
)fn price_authority(env: soroban_sdk::Env) -> OptionResolves what a specific purchase attempt actually minted — see
[Self::buy_edition]'s doc comment for why this, and not the
transaction's return value, is how a confirmation step learns the
assigned token range.
fn purchase_by_ref(
env: soroban_sdk::Env,
purchase_ref: soroban_sdk::String,
) -> OptionCalled by the backend once it has independently verified (off-chain)
that this specific token's specific locked-content item had its
unlock rule completed. Idempotent — calling it again for an
already-unlocked (token, item) pair is a no-op, not an error, so a
retried backend call after a dropped response is safe. Keyed by
(token_id, media_index) alone, not edition or owner: each item's
rule applies to one specific minted copy, decided once, regardless
of who holds it later.
fn unlock_item_for(
env: soroban_sdk::Env,
caller: soroban_sdk::Address,
token_id: u32,
media_index: u32,
)Accepts a pending ownership transfer.
e - Access to the Soroban environment.crate::role_transfer::RoleTransferError::NoPendingTransfer] - If
there is no pending transfer to accept.["ownership_transfer_completed"][new_owner: Address]fn accept_ownership(env: soroban_sdk::Env)Public, permissionless read — anyone (the buyer, a marketplace UI, an auditor) can verify on-chain whether a given token's given locked-content item was unlocked, without trusting the backend's word for it.
fn is_item_unlocked(env: soroban_sdk::Env, token_id: u32, media_index: u32) -> boolfn platform_fee_bps(env: soroban_sdk::Env) -> u32fn remaining_supply(env: soroban_sdk::Env, edition_id: u32) -> u32fn set_platform_fee(
env: soroban_sdk::Env,
fee_bps: u32,
treasury: soroban_sdk::Address,
)Renounces ownership of the contract.
Permanently removes the owner, disabling all functions gated by
#[only_owner].
e - Access to the Soroban environment.OwnableError::TransferInProgress] - If there is a pending ownership
transfer.OwnableError::OwnerNotSet] - If the owner is not set.fn renounce_ownership(env: soroban_sdk::Env)Initiates a 2-step ownership transfer to a new address.
Requires authorization from the current owner. The new owner must later
call accept_ownership() to complete the transfer.
e - Access to the Soroban environment.new_owner - The proposed new owner.live_until_ledger - Ledger number until which the new owner can
accept. A value of 0 cancels any pending transfer.OwnableError::OwnerNotSet] - If the owner is not set.crate::role_transfer::RoleTransferError::NoPendingTransfer] - If
trying to cancel a transfer that doesn't exist.crate::role_transfer::RoleTransferError::InvalidLiveUntilLedger] -
If the specified ledger is in the past.crate::role_transfer::RoleTransferError::InvalidPendingAccount] -
If the specified pending account is not the same as the provided new
address.fn transfer_ownership(
env: soroban_sdk::Env,
new_owner: soroban_sdk::Address,
live_until_ledger: u32,
)Returns whether the operator is allowed to manage all the assets of
owner.
e - Access to the Soroban environment.owner - Account of the token's owner.operator - Account to be checked.fn is_approved_for_all(
env: soroban_sdk::Env,
owner: soroban_sdk::Address,
operator: soroban_sdk::Address,
) -> boolRotates the price authority's hot key — same rationale as
set_unlock_authority: this key gets called by the backend on
every creator edit, so being able to swap it without touching the
owner's cold key matters.
fn set_price_authority(env: soroban_sdk::Env, new_authority: soroban_sdk::Address)Rotates the unlock authority's hot key without a full upgrade — the backend process holding this key gets called automatically and often, so being able to swap it (e.g. after a suspected leak) without touching the owner's cold key matters more here than for most admin settings.
fn set_unlock_authority(env: soroban_sdk::Env, new_authority: soroban_sdk::Address)