User Guide

Soulidity uses a Sui wallet challenge-response for login. The web app issues a server-signed challenge, your wallet signs it, and the server sets an HTTP-only session cookie. No purchase or mint transaction is sent at login.

• Click Login in the navbar and pick any Sui wallet. Each account is bound to one primary wallet — the wallet you first sign in with is the one Soulidity uses for ownership lookups.
• Fund the wallet with SUI (for gas + Walrus storage) and USDC on Sui (for purchases and paid access). All Soulidity prices are denominated in atomic USDC on-chain.
• If you do not yet have a personal kiosk, the first publish or purchase transaction creates one for you automatically. All your Souls are held in this single kiosk.

Listed Souls appear on the market. Each card shows the cover image, name, creator, USDC price, and tag chips. Unlisted (held) Souls are private to the owner.

• Use the tag filter and search to narrow listings.
• Click any card to open the Soul detail page — description, full preview, current owner, creator royalty rate, collection membership, and any active grants.
• If the Soul belongs to a Collection, the collection page also shows its peers, an extra collection royalty rate, and the on-chain supply cap.

1. Open a listing and click Buy. The price is shown in human USDC; the on-chain value is in atomic units (1 USDC = 1 000 000 atomic).
2. Review the fee split — platform fee + creator royalty (+ optional collection royalty). All splits are applied atomically by the market module; the price you pay is the final amount.
3. Approve the transaction in your wallet. The TX calls market::buy_from_personal_kiosk, which moves the Soul from the seller's personal kiosk into yours in a single step.
4. The app then mirrors the new owner in the database. All active SoulGrants and paid-access entries on this Soul are invalidated immediately via the ownership_epoch bump — anything the previous owner authorized stops working before you take possession.
5. The Soul appears in My Souls. From there you can list it, transfer it into a collection, grant agents access, or bind it to the desktop companion.

Go to Create. You will need the following inputs — all live as typed content slots under one unified SoulContent object (see Kind Registry).

• soul.md (KIND_SOUL_DOC) — the five-section character document. Appended once at mint and forever immutable. See Content Format for the template.
• memory.md (KIND_MEMORY, optional) — the founding memory entry. Append-only timeline you (or granted agents) can extend later.
• skills.zip (KIND_SKILL, optional) — an initial skills bundle. The ZIP must contain a SKILL.md with a name front-matter field.
• Sprite (KIND_SPRITE, optional) — persona art for the desktop companion. Can be made public, paid-gated, or grant-gated.
• Audio (KIND_AUDIO, optional) — persona voice for the desktop companion. Same read-mode options as sprite.
• A cover image URL, description, tags, and creator royalty (basis points) for the marketplace listing.
• SUI for gas plus any Walrus blob registration fees charged by the storage network.

After signing the publish TX, your Soul appears in your profile. You can list it for sale at any time from the Soul detail page. Mint creates the on-chain SoulContent typed-content root and a per-Soul SoulPaidAccessList bound 1:1 to the Soul.

Once a Soul is minted, you can keep appending new versions to mutable kinds (memory, skill, sprite, audio). Only soul_doc is permanently sealed at mint.

• Append — adds a new immutable version. Past versions remain queryable (subject to read mode).
• Soft delete — flags a version as deleted; encrypted blob stays on Walrus.
• Hard purge — clears the on-chain pointer entirely. Owner only.
• Active binding (sprite / audio only) — selects which uploaded version is the live persona. The desktop companion reads from the active slot.

When you append a non-public version, Soulidity automatically issues scope-matched SoulGrants to every active agent on your account that doesn't already hold the required scope. This lets your agents (e.g. OpenClaw, Hermes) keep reading newly added content without manual re-authorization. If the auto-grant call fails — for example during a deploy window — the My Souls page surfaces a yellow banner telling you exactly which agents are missing which scopes, and you can retry from there.

See Agent Integration for the full auto-grant rules.

A SoulGrant is an on-chain delegation that lets a specific wallet (typically an AI agent) read or write specific Soul data channels without transferring ownership. Each grant carries a scope_mask:

• SCOPE_SEAL = 1 → decrypt the soul_doc bundle
• SCOPE_MEMORY = 2 → read memory entries and append new ones
• SCOPE_SKILLS = 4 → read private skill versions and publish new ones
• SCOPE_ASSETS = 8 → read private sprite/audio versions and publish new ones

Each Soul has one grant slot per grantee. Issuing a second grant to the same grantee supersedes the first — the new scope_mask fully replaces the old one (it is not union-ed). Use the pre-check endpoint POST /api/souls/grant-merge-masks to compute the intended existing | added mask before signing if you want to extend rather than overwrite. The Soulidity SDK helpers handle this for you.

All grants are invalidated automatically when the Soul changes hands via the ownership_epoch snapshot on each grant. You never need to revoke before selling — the rotation is implicit.

See SoulGrant API for the full lifecycle (issue / supersede / revoke / expire).

Sprite and audio kinds support paid access — viewers can purchase time-bound (or lifetime) access to your persona assets in USDC. Memory, skill, and soul_doc kinds do not support paid access; those channels stay owner + granted-agent only.

As the Soul owner, you configure KindPaidConfig per kind: price in atomic USDC, scope mask (pinned to the kind's default), and an optional duration. Buyers call the purchase route, USDC is split per platform / creator / collection fees, and a KindPaidEntry is recorded under their address.

Important: paid access is an owner-revocable subscription, not a permanent purchase. You may call paid_access::revoke_access at any time and no on-chain refund is issued. Entries also auto-invalidate when the Soul changes ownership. Anyone purchasing access should treat this as a recurring subscription on your goodwill, not a sale.

See Paid Access for the full revocation, renewal, and stale-entry-cleanup model.

The Soulidity desktop app renders any Soul you own (or hold a grant for) as a live persona on your desktop — sprite animation, voice, memory-aware chat. The web → desktop handoff is:

1. Mint By Web can notify the desktop app with soulidity://mint-completed?token=... so the desktop clears its local extract draft and returns to the scan step. The current desktop handler does not deep-link a Soul ID or purchase directly into the persona library.
2. If the sprite / audio version is paid- or grant-gated, the desktop app prompts you to authorize: it issues a SoulGrant with SCOPE_ASSETS to itself.
3. Protected sprite decryption happens locally through the soul:decrypt-protected-sprite IPC. The main process decrypts the Walrus blob and returns sprite bytes to the renderer, which immediately passes them back to soul:cache-persona for the local desktop cache.

See Desktop Companion for installation, upgrade, and IPC protocol details.

• List for sale. Open My Souls → pick the Soul → List. Set the USDC price (and optionally bind to a collection). Listed Souls cannot be moved into collections until you cancel the listing.
• Cancel a listing. The shared listing object is consumed by market::cancel_soul_listing; storage rebate is reclaimed. Any caller may also reap inactive listings via delete_soul_listing.
• Transfer to a collection. If you control a collection, you can bind a Soul into it via collection::add_soul. The Soul cannot be in an active listing at the time. The collection's max_supply cap is enforced on-chain.
• On ownership change. The Soul's ownership_epoch bumps. Every outstanding SoulGrant and every KindPaidEntry is automatically invalidated through the epoch snapshot. The new owner inherits a clean slate; old grants can be reaped by anyone via grant::destroy_invalidated_grant to reclaim storage rebate.