Paid Access

The 1:1 SoulPaidAccessList model

Every Soul minted on phase 2 has exactly one SoulPaidAccessList shared object, created at mint and bound to the Soul via SoulState.access_list_id. It holds:

• A kind_configs: Table<u32, KindPaidConfig> — one config per kind the owner has opened up to paid access. Configs are added with configure_paid_access_kind and removed with delete_paid_access_kind.
• An entries: Table<address, Table<u32, KindPaidEntry>> — buyer rows, keyed by address then by kind. Inner rows are created lazily on first purchase and reaped when emptied.

public struct KindPaidConfig has copy, drop, store {
    version: u64,
    price_atomic: u64,
    scope_mask: u64,            // pinned to kind's default_grant_scope_mask
    duration_ms: Option<u64>,   // None = lifetime
    ownership_epoch_snapshot: u64,
}

public struct KindPaidEntry has copy, drop, store {
    version: u64,
    scope_mask: u64,
    expires_at_ms: Option<u64>,
    ownership_epoch_snapshot: u64,
}

Which kinds support paid access

Paid access only applies to kinds whose read_mode_mask includes READ_PAID. Among the five built-in kinds:

Custom kinds registered through kind_registry::register_kind may opt into READ_PAID (admin-only registration). See Kind Registry.

Purchase flow

1. Owner configures the kind with configure_paid_access_kind: price in atomic USDC, scope mask (must equal the kind's default_grant_scope_mask), and an optional duration_ms. The config snapshots the current ownership epoch.
2. Buyer signs a purchase TX. The market module splits USDC (platform fee + creator royalty + optional collection royalty) and calls paid_access::record_purchase internally.
3. record_purchase asserts the config's epoch matches the current epoch (rejecting purchases against a stale config from a previous owner), computes the new expires_at_ms from the renewal base, and writes a fresh KindPaidEntry under the buyer's row.
4. The post-TX API mirrors the entry into SoulPaidAccessEntry for the My Souls UI and any indexers.

Free access can be granted by the owner via paid_access::add_access, which writes the same entry shape with price_paid_atomic = 0 and a SoulPaidAccessGranted event.

Renewal & expiry

• Time-bound entry. When duration_ms is Some(d), the entry's expires_at_ms = renewal_base + d. The renewal base is max(now, previous_expires_at_ms) — re-purchasing before expiry extends from the existing end, not from now.
• Lifetime entry. When duration_ms is None, the entry has no expiry and a re-purchase aborts with EAlreadyHasAccess — there is nothing to renew.
• Stale-epoch overwrite. If the entry pre-dates the current ownership epoch, the buyer's next purchase overwrites it instead of aborting — the old entry was already invalidated.

Owner revoke

paid_access::revoke_access(grantee, kind) removes the buyer's entry and emits SoulPaidAccessRevoked. Subsequent seal_approve_content_paid_access calls for that buyer fail until they re-purchase. The owner may also content::delete_* or purge_* the underlying slot, which makes the entry useless even without explicit revoke.

No on-chain refund rail exists. Any refund or credit policy must be handled off-chain. If you intend to offer guaranteed-term access, build a slot-level delete lock and an explicit refund path into your front-end — the protocol does not enforce one.

Ownership-epoch auto-invalidation

Every KindPaidEntry snapshots ownership_epoch at write time. has_access and seal_approve_content_paid_access require the snapshot to equal the Soul's current ownership_epoch, so all entries auto-invalidate when the Soul changes hands. The new owner inherits an effectively-empty list. Buyers can re-purchase under the new owner, which overwrites the stale row.

Stale-entry cleanup

Invalidated entries hold no value; reaping them reclaims storage rebate. paid_access::cleanup_stale_entries is callable by anyone and takes parallel vector<address> + vector<u32> arguments. It removes entries whose snapshot is stale, and drops the outer buyer row when its inner table is empty. Indexers and bots typically run a periodic cleanup pass after high-volume ownership rotations.

Paid access vs SoulGrant

REST API

• POST /api/souls/[id]/paid-access
  Mirror an owner revoke paid-access TX. Body includes action: "revoke", txDigest, buyerAddress, and kind. The route is idempotent on digest.