Getting Started

1. Connect Your Wallet

Soulidity authenticates humans with a Sui wallet signature challenge. The app writes a session cookie after you sign the challenge; your wallet remains under your control.

• Click Connect in the top navigation bar.
• Select a Sui wallet and approve the login message. No purchase or mint transaction is sent during login.
• Your wallet address is visible in your profile. Each account has one primary Sui wallet for Soulidity actions.
• USDC on Sui is required for purchases. Fund your connected wallet before buying.

2. Browse Souls

All listed Souls are visible on the marketplace. Each card shows the Soul name, creator, listed price in USDC, and tags.

• Use the tag filter and search to narrow results.
• Click a Soul card to view its detail page — description, preview images, and grant status.
• The Soul detail page shows the current owner, creator royalty rate, and any active collection membership.
• Unlisted (held) Souls are not shown in the public marketplace.

3. Make Your First Purchase

1. Open a Soul listing and click Buy. The price is shown in USDC atomic units.
2. Review the fee breakdown — platform fee + creator royalty (+ optional collection royalty). Fees are deducted from the purchase amount on-chain atomically.
3. Approve the transaction in your connected wallet. The TX calls market::buy_from_personal_kiosk which moves the Soul from the seller's kiosk to your personal kiosk in a single atomic step.
4. After the TX confirms, the app calls the post-TX API to mirror the new owner in the DB. All active grants on the Soul are invalidated automatically at this point.
5. The Soul now appears in your My Souls page.

4. Ownership Model

Soulidity uses a personal kiosk ownership model. Every user has one personal kiosk on Sui that holds their Souls. You cannot transfer Souls directly to an address — all transfers go through the kiosk and market contract.

• Soul object: The actual NFT held inside your kiosk. It contains the encrypted content blob.
• SoulState: A shared object that tracks ownership, grants, and bound IDs (memory, skills, collection). Anyone can read it; only the owner can modify it.
• On-chain is authoritative: The DB is a mirror. If the DB and chain disagree, chain wins. Access routes fetch live chain state before issuing decryption keys.
• Ownership epoch: Each ownership transfer increments an epoch counter on SoulState. All outstanding SoulGrants are invalidated immediately on transfer — previously issued agent grants stop working the moment you buy or sell a Soul.

5. Publish Your First Soul

To publish a Soul, go to Create. You will need:

• soul.md — a five-section character document. See the Content Format guide for the template.
• memory.md (optional) — a founding memory entry. Encrypted at upload.
• skill.zip (optional) — an initial skills bundle. The ZIP must contain a SKILL.md with a name frontmatter field.
• A cover image URL and description for the marketplace listing.
• SUI for gas and any Walrus 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.

Next Steps