Skip to main content

API Reference

This page lists the current developer-facing Move API in the protocol and market packages. It documents public entry functions, public helpers, key public structs, and module boundaries as they exist in source today.

Module organization​

The public API is split into these modules:

  • mercatr::index — shared quadtree index and parcel lookup
  • mercatr::mutations — low-level geometry mutations gated by LifecycleCap
  • mercatr::admin — governed index creation, cap rotation, and sealing
  • mercatr_market::pricing — pure pricing math and PriceState
  • mercatr_market::market — shared market object, levels, treasury, pause, and tax wrappers
  • mercatr_market::trading — register, buy, price bump, price drop, and governed remove
  • mercatr_market::parcel_ops — expand, acquire, rebalance, split, and merge
  • mercatr_market::proposals — POI proposal boards and proposal lifecycle
  • mercatr_market::marks — parcel and POI marks

mercatr_market::revenue is not public API. Its functions are public(package) and exist only for internal payment routing.

mercatr::index​

The index stores parcels in a quadtree and exposes the core parcel registry.

Public structs​

Config

public struct Config has copy, drop, store {
max_vertices: u64,
max_parts_per_polygon: u64,
scaling_factor: u64,
max_broadphase_span: u64,
max_cell_occupancy: u64,
max_probes_per_call: u64,
}

Index

public struct Index has key, store {
id: object::UID,
cells: Table<u64, vector<ID>>,
polygons: Table<ID, Polygon>,
cell_size: u64,
max_depth: u8,
count: u64,
occupied_depths: u32,
config: Config,
authorized_caps: VecSet<ID>,
authorization_sealed: bool,
}

TransferCap

public struct TransferCap has key, store {
id: object::UID,
index_id: ID,
}

LifecycleCap

public struct LifecycleCap has key, store {
id: object::UID,
index_id: ID,
}

Public functions​

public fun register(
_cap: &LifecycleCap,
index: &mut Index,
parts_xs: vector<vector<u64>>,
parts_ys: vector<vector<u64>>,
ctx: &mut tx_context::TxContext,
): ID

Registers a parcel and returns its object ID.

public fun remove(
_cap: &LifecycleCap,
index: &mut Index,
polygon_id: ID,
ctx: &mut tx_context::TxContext,
)
public fun transfer_ownership(
_cap: &LifecycleCap,
index: &mut Index,
polygon_id: ID,
new_owner: address,
ctx: &tx_context::TxContext,
)
public fun force_transfer(
_cap: &TransferCap,
index: &mut Index,
polygon_id: ID,
new_owner: address,
)
public fun candidates(index: &Index, query_id: ID): vector<ID>
public fun overlaps(index: &Index, id_a: ID, id_b: ID): bool
public fun outer_contains_inner(
outer_index: &Index,
outer_id: ID,
inner_index: &Index,
inner_id: ID,
): bool
public fun overlapping(index: &Index, query_id: ID): vector<ID>
public fun query_viewport(
index: &Index,
min_x: u64,
min_y: u64,
max_x: u64,
max_y: u64,
): vector<ID>
public fun new_config(
max_vertices: u64,
max_parts_per_polygon: u64,
scaling_factor: u64,
max_broadphase_span: u64,
max_cell_occupancy: u64,
max_probes_per_call: u64,
): Config
public fun is_sealed(index: &Index): bool
public fun count(index: &Index): u64
public fun cell_size(index: &Index): u64
public fun max_depth(index: &Index): u8
public fun max_vertices_per_part(index: &Index): u64
public fun max_parts_per_polygon(index: &Index): u64
public fun scaling_factor(index: &Index): u64
public fun max_broadphase_span(index: &Index): u64
public fun max_cell_occupancy(index: &Index): u64
public fun max_probes_per_call(index: &Index): u64
public fun get(index: &Index, polygon_id: ID): &Polygon

Package-only internals​

new, with_config, share, share_existing, share_with_config, remove_unchecked, set_config, authorize_cap, seal, unseal, destroy_empty, and the geometry helpers are public(package). Call mercatr::admin for governed index creation and cap management.

mercatr::mutations​

These functions mutate parcel geometry. They are public, but the intended caller is the market layer.

public fun reshape_unclaimed(
cap: &LifecycleCap,
index: &mut Index,
polygon_id: ID,
new_parts_xs: vector<vector<u64>>,
new_parts_ys: vector<vector<u64>>,
ctx: &tx_context::TxContext,
)
public fun repartition_adjacent(
cap: &LifecycleCap,
index: &mut Index,
a_id: ID,
a_parts_xs: vector<vector<u64>>,
a_parts_ys: vector<vector<u64>>,
b_id: ID,
b_parts_xs: vector<vector<u64>>,
b_parts_ys: vector<vector<u64>>,
ctx: &tx_context::TxContext,
)
public fun split_replace(
cap: &LifecycleCap,
index: &mut Index,
parent_id: ID,
children_parts_xs: vector<vector<vector<u64>>>,
children_parts_ys: vector<vector<vector<u64>>>,
ctx: &mut tx_context::TxContext,
): vector<ID>
public fun merge_keep(
cap: &LifecycleCap,
index: &mut Index,
keep_id: ID,
absorb_id: ID,
merged_parts_xs: vector<vector<u64>>,
merged_parts_ys: vector<vector<u64>>,
ctx: &tx_context::TxContext,
)
public fun remove_polygon(
cap: &LifecycleCap,
index: &mut Index,
polygon_id: ID,
ctx: &mut tx_context::TxContext,
)

mercatr::admin​

This module creates indexes, mints and revokes capabilities, and seals or unseals authorization.

Public struct​

public struct AdminCap has key, store {
id: sui::object::UID,
}

Public functions​

public fun update_config(
_: &AdminCap,
index: &mut Index,
new_config: Config,
)
public fun create_index(
_: &AdminCap,
cell_size: u64,
max_depth: u8,
max_broadphase_span: u64,
max_cell_occupancy: u64,
max_probes_per_call: u64,
ctx: &mut sui::tx_context::TxContext,
): Index
public fun share_index(index: Index)
public fun destroy_index(_: &AdminCap, index: Index)
public fun mint_transfer_cap(
_: &AdminCap,
index: &mut Index,
ctx: &mut sui::tx_context::TxContext,
): TransferCap
public fun mint_lifecycle_cap(
_: &AdminCap,
index: &mut Index,
ctx: &mut sui::tx_context::TxContext,
): LifecycleCap
public fun mint_lifecycle_cap_with_id(
_: &AdminCap,
index: &mut Index,
ctx: &mut sui::tx_context::TxContext,
): (LifecycleCap, sui::object::ID)
public fun mint_caps_with_ids(
_: &AdminCap,
index: &mut Index,
ctx: &mut sui::tx_context::TxContext,
): (TransferCap, LifecycleCap, sui::object::ID, sui::object::ID)
public fun authorize_cap(
_: &AdminCap,
index: &mut Index,
cap_id: sui::object::ID,
)
public fun revoke_transfer_cap(
_: &AdminCap,
index: &mut Index,
cap_id: sui::object::ID,
)
public fun revoke_lifecycle_cap(
_: &AdminCap,
index: &mut Index,
cap_id: sui::object::ID,
)
public fun seal_index(_: &AdminCap, index: &mut Index)
public fun unseal_index(_: &AdminCap, index: &mut Index)

Disabled function​

admin::force_remove is disabled in current code. The source keeps only a commented-out implementation and the production path is mercatr_market::trading::remove, which also cleans up PriceState, tax state, and metadata.

mercatr_market::pricing​

This module holds pure pricing math.

Public struct​

public struct PriceState has copy, drop, store {
premium_ppm: u64,
sale_count: u64,
}

Public functions​

public fun next_resale_premium_ppm(
current_premium_ppm: u64,
sale_idx: u64,
): u64
public fun prev_resale_premium_ppm(
current_premium_ppm: u64,
current_sale_count: u64,
): u64
public fun post_registration_premium_ppm(): u64
public fun quote_price_from_premium(
area_m2: u64,
price_per_km2_mist: u64,
premium_ppm: u64,
): u64
public fun seller_proceeds_for_price(price: u64): u64
public fun treasury_fee_for_price(price: u64): u64
public fun hierarchy_pool_for_price(price: u64): u64

Removed names from older docs do not exist anymore. Do not call calculate_price or next_premium.

mercatr_market::market​

This module owns the shared market object, level registry, treasury, pause switch, and tax wrappers.

Public structs​

Level

public struct Level has copy, drop, store {
index_id: sui::object::ID,
price_per_km2_mist: u64,
min_area_m2: u64,
max_area_m2: u64,
}

MarketInner

public struct MarketInner has store {
version: u64,
transfer_cap: index::TransferCap,
lifecycle_cap: index::LifecycleCap,
treasury: Balance<SUI>,
price_states: Table<sui::object::ID, PriceState>,
levels: vector<Level>,
}

Market

public struct Market has key {
id: sui::object::UID,
paused: bool,
inner: Versioned,
}

Market stores its mutable core state inside inner: Versioned. Callers see a shared Market, but the actual market fields live in MarketInner behind the versioned wrapper.

MarketAdminCap

public struct MarketAdminCap has key, store {
id: sui::object::UID,
}

Public functions​

public fun new(
transfer_cap: index::TransferCap,
lifecycle_cap: index::LifecycleCap,
ctx: &mut sui::tx_context::TxContext,
): Market
public fun share(market: Market)
public fun swap_caps(
_admin: &MarketAdminCap,
market: &mut Market,
new_transfer_cap: index::TransferCap,
new_lifecycle_cap: index::LifecycleCap,
_ctx: &mut sui::tx_context::TxContext,
): (index::TransferCap, index::LifecycleCap)
public fun add_level(
_admin: &MarketAdminCap,
market: &mut Market,
index: &index::Index,
price_per_km2_mist: u64,
min_area_m2: u64,
max_area_m2: u64,
)
public fun update_level(
_admin: &MarketAdminCap,
market: &mut Market,
level_index: u64,
price_per_km2_mist: u64,
min_area_m2: u64,
max_area_m2: u64,
)
public fun withdraw(
_admin: &MarketAdminCap,
market: &mut Market,
amount: u64,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>
public fun pause(_admin: &MarketAdminCap, market: &mut Market)
public fun unpause(_admin: &MarketAdminCap, market: &mut Market)
public fun is_paused(market: &Market): bool
public fun treasury_balance(market: &Market): u64
public fun premium_ppm(market: &Market, polygon_id: sui::object::ID): u64
public fun sale_count(market: &Market, polygon_id: sui::object::ID): u64
public fun init_tax(
_admin: &MarketAdminCap,
market: &mut Market,
upstream_tax_bps: u64,
ctx: &mut sui::tx_context::TxContext,
)

upstream_tax_bps is still present in the call shape and is passed into tax::init_tax.

public fun set_tax_level_cfg(
_admin: &MarketAdminCap,
market: &mut Market,
level_index: u64,
cfg: tax::TaxLevelCfg,
)
public fun collect_tax(
market: &mut Market,
parent_index: &index::Index,
parent_id: sui::object::ID,
child_index: &index::Index,
child_ids: vector<sui::object::ID>,
child_bucket_ids: vector<u64>,
ctx: &mut sui::tx_context::TxContext,
)

This signature does not include child_versions.

public fun sweep_expired(
market: &mut Market,
polygon_id: sui::object::ID,
version: u64,
bucket_id: u64,
ctx: &mut sui::tx_context::TxContext,
)
public fun tax_is_initialized(market: &Market): bool
public fun tax_fund_balance(market: &Market): u64
public fun tax_version_counter(
market: &Market,
polygon_id: sui::object::ID,
): u64
public fun tax_self_claimable(
market: &Market,
polygon_id: sui::object::ID,
): u64

mercatr_market::trading​

This module exposes the main market entry points.

Public entry functions and helpers​

entry fun register(
market: &mut Market,
index: &mut index::Index,
parts_xs: vector<vector<u64>>,
parts_ys: vector<vector<u64>>,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): (sui::object::ID, Coin<SUI>)

The registration payment splits into 92% treasury and 8% hierarchy pool. The returned tuple is the new parcel ID plus the leftover payment coin.

entry fun buy_full(
market: &mut Market,
index: &mut index::Index,
polygon_id: sui::object::ID,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>

buy_full returns the leftover payment coin. Its payment split is 85% seller, 7% treasury, 8% hierarchy pool.

entry fun bump_price(
market: &mut Market,
index: &index::Index,
polygon_id: sui::object::ID,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>
entry fun drop_price(
market: &mut Market,
index: &index::Index,
polygon_id: sui::object::ID,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>
public fun current_price(
market: &Market,
index: &index::Index,
polygon_id: sui::object::ID,
): u64
public fun quote_bump_cost(
market: &Market,
index: &index::Index,
polygon_id: sui::object::ID,
): u64
public fun quote_drop_cost(
market: &Market,
index: &index::Index,
polygon_id: sui::object::ID,
): u64
public fun remove(
_admin: &MarketAdminCap,
market: &mut Market,
index: &mut index::Index,
polygon_id: sui::object::ID,
ctx: &mut sui::tx_context::TxContext,
)

mercatr_market::parcel_ops​

These functions change parcel geometry through the market layer.

public fun expand_unclaimed(
market: &mut Market,
index: &mut index::Index,
polygon_id: sui::object::ID,
new_parts_xs: vector<vector<u64>>,
new_parts_ys: vector<vector<u64>>,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>

expand_unclaimed charges only for the added area and uses the same 92/8 treasury and hierarchy split as registration.

public fun acquire_slice(
market: &mut Market,
index: &mut index::Index,
receiver_id: sui::object::ID,
donor_id: sui::object::ID,
receiver_new_xs: vector<vector<u64>>,
receiver_new_ys: vector<vector<u64>>,
donor_new_xs: vector<vector<u64>>,
donor_new_ys: vector<vector<u64>>,
mut payment: Coin<SUI>,
ctx: &mut sui::tx_context::TxContext,
): Coin<SUI>

The protocol prices the captured area at the donor's current premium. After the transfer, the donor keeps its old premium_ppm, and the receiver gets the area-weighted blend of its old premium plus the acquired slice, rounded up with a ceiling division.

public fun rebalance_slice(
market: &mut Market,
index: &mut index::Index,
a_id: sui::object::ID,
a_new_xs: vector<vector<u64>>,
a_new_ys: vector<vector<u64>>,
b_id: sui::object::ID,
b_new_xs: vector<vector<u64>>,
b_new_ys: vector<vector<u64>>,
ctx: &mut sui::tx_context::TxContext,
)

rebalance_slice sets both parcels to the same area-weighted average premium, rounded up, and the max sale_count of the pair.

public fun split_owned(
market: &mut Market,
index: &mut index::Index,
parent_id: sui::object::ID,
children_parts_xs: vector<vector<vector<u64>>>,
children_parts_ys: vector<vector<vector<u64>>>,
ctx: &mut sui::tx_context::TxContext,
): vector<sui::object::ID>
public fun merge_owned(
market: &mut Market,
index: &mut index::Index,
keep_id: sui::object::ID,
absorb_id: sui::object::ID,
merged_parts_xs: vector<vector<u64>>,
merged_parts_ys: vector<vector<u64>>,
ctx: &mut sui::tx_context::TxContext,
)

merge_owned gives the survivor the area-weighted average premium, rounded up, and the max sale_count.

mercatr_market::proposals​

This module manages POI proposal boards and escrowed offers.

Public structs​

ProposalBoard

public struct ProposalBoard has key {
id: object::UID,
block_index_id: object::ID,
min_proposal_fee: u64,
max_per_polygon: u64,
max_per_proposer: u64,
pending_ttl_epochs: u64,
proposal_counter: u64,
escrow: Balance<SUI>,
}

Proposal

public struct Proposal has drop, store {
polygon_id: object::ID,
proposer: address,
poi_name: vector<u8>,
poi_coord_x: u64,
poi_coord_y: u64,
poi_icon: std::option::Option<vector<u8>>,
details_cid: std::option::Option<std::string::String>,
offer_amount: u64,
status: u8,
created_epoch: u64,
}

Public entry functions​

entry fun create_proposal_board(
_admin: &market::MarketAdminCap,
block_index_id: object::ID,
min_proposal_fee: u64,
max_per_polygon: u64,
max_per_proposer: u64,
pending_ttl_epochs: u64,
ctx: &mut tx_context::TxContext,
)
entry fun set_min_offer(
board: &mut ProposalBoard,
index: &Index,
polygon_id: object::ID,
min_offer: u64,
ctx: &tx_context::TxContext,
)
entry fun propose_poi(
board: &mut ProposalBoard,
market: &mut market::Market,
index: &Index,
polygon_id: object::ID,
poi_name: vector<u8>,
poi_coord_x: u64,
poi_coord_y: u64,
poi_icon: std::option::Option<vector<u8>>,
details_cid: std::option::Option<std::string::String>,
mut payment: Coin<SUI>,
ctx: &mut tx_context::TxContext,
)
entry fun accept_proposal(
board: &mut ProposalBoard,
market: &mut market::Market,
index: &Index,
proposal_id: u64,
ctx: &mut tx_context::TxContext,
)
entry fun reject_proposal(
board: &mut ProposalBoard,
index: &Index,
proposal_id: u64,
ctx: &mut tx_context::TxContext,
)
entry fun withdraw_proposal(
board: &mut ProposalBoard,
proposal_id: u64,
ctx: &mut tx_context::TxContext,
)
entry fun prune_pending(
board: &mut ProposalBoard,
proposal_id: u64,
ctx: &mut tx_context::TxContext,
)

Public getters​

public fun board_escrow_value(board: &ProposalBoard): u64
public fun board_proposal_counter(board: &ProposalBoard): u64
public fun get_proposal(board: &ProposalBoard, proposal_id: u64): &Proposal
public fun proposal_polygon_id(p: &Proposal): object::ID
public fun proposal_proposer(p: &Proposal): address
public fun proposal_poi_name(p: &Proposal): vector<u8>
public fun proposal_poi_coord_x(p: &Proposal): u64
public fun proposal_poi_coord_y(p: &Proposal): u64
public fun proposal_poi_icon(p: &Proposal): std::option::Option<vector<u8>>
public fun proposal_details_cid(
p: &Proposal,
): std::option::Option<std::string::String>
public fun proposal_offer_amount(p: &Proposal): u64
public fun proposal_status(p: &Proposal): u8
public fun proposal_created_epoch(p: &Proposal): u64
public fun get_polygon_proposal_ids(
board: &ProposalBoard,
polygon_id: object::ID,
): vector<u64>

The proposal fee floor goes to treasury. Any excess stays in escrow until accept, reject, withdraw, or expiry.

mercatr_market::marks​

This module records paid reactions on parcels and accepted POIs.

Public struct​

public struct MarkBoard has key {
id: object::UID,
}

Public entry functions​

entry fun create_board(
_admin: &market::MarketAdminCap,
ctx: &mut tx_context::TxContext,
)
entry fun mark(
board: &mut MarkBoard,
market: &mut market::Market,
index: &Index,
polygon_id: object::ID,
mark_type: u8,
payment: Coin<SUI>,
ctx: &mut tx_context::TxContext,
)
entry fun mark_poi(
board: &mut MarkBoard,
market: &mut market::Market,
proposal_board: &proposals::ProposalBoard,
index: &Index,
proposal_id: u64,
mark_type: u8,
payment: Coin<SUI>,
ctx: &mut tx_context::TxContext,
)

Public getters​

public fun get_poi_marks(
board: &MarkBoard,
proposal_id: u64,
): vector<u64>
public fun get_marks(
board: &MarkBoard,
polygon_id: object::ID,
): vector<u64>

Internal revenue module​

mercatr_market::revenue contains only public(package) functions:

public(package) fun route_hierarchy_pool(...): Balance<SUI>
public(package) fun deposit_revenue(...): (Balance<SUI>, Balance<SUI>)
public(package) fun collect_treasury_fee(...): Balance<SUI>
public(package) fun route_mark_payment(...): Balance<SUI>

Treat this module as internal plumbing, not as a public integration surface.