BOXPOOL HELP
Boxpool on PulseChain

Version: 1.0
Date: 2026-05-31

====================================================================
1) WHAT BOXPOOL IS
====================================================================

Boxpool is a privacy pool control room for PulseChain.
It lets you:
- Shield assets into a privacy pool
- Save and manage local Boxpool notes
- Unshield later with zero-knowledge proof flow
- Review balances, pool addresses, and note history in one place

Boxpool is designed for users who want practical privacy with explicit
controls and predictable behavior.

====================================================================
2) IMPORTANT NOTE SAFETY WARNINGS
====================================================================

Read this before you shield anything.

- Save your note immediately after shielding.
- Back up notes before clearing browser data.
- Do not lose the note if you expect to unshield later.
- A note is your proof material and recovery record.
- If a note is deleted, hidden, or overwritten, recovery may be impossible.
- Keep backups in more than one place if the value matters.

Critical security warning:
- Browser local storage is not a hardware vault.
- If your device is compromised, saved notes can be stolen.
- Malware, malicious browser extensions, keyloggers, clipboard stealers,
  and remote-access trojans can expose note data.
- A phishing page or fake app can trick you into pasting/exporting notes.
- If someone gains OS account access, local browser data may be copied.
- Assume a normal daily-use browser is high risk for large-value notes.

For large amounts:
- Do not rely on normal browser local storage as your only protection.
- Use offline backups and safer operational practices.
- Consider dedicated devices/profiles with minimal extensions.
- Treat note compromise as equivalent to potential fund compromise.

Best practice:
- Copy the note
- Download the note JSON
- Confirm the backup exists
- Only then close the browser or move to the next step

If you are using Local Notes, remember:
- Session mode keeps notes only in the current browser session
- Local Notes Storage mode stores encrypted notes locally with your password
- Use a strong password and do not reuse it casually

====================================================================
3) CORE FEATURES
====================================================================

Shielding:
- Deposit DEX or PLS into a privacy pool
- Generate a Boxpool note after the transaction
- Keep the note safe for future unshielding

Local Notes:
- View your saved notes
- Copy or download notes
- Hide notes you do not want in the main list
- Restore hidden notes later
- Back up and delete all notes when needed

Persistence:
- Session-only note storage by default
- Optional encrypted Local Notes Storage in local storage
- Unlock persisted notes with a password

Unshielding:
- Choose a ready note
- Select a recipient
- Choose an amount
- Review the request payload
- Generate proof
- Submit through the chosen mode

====================================================================
4) SHIELDING GUIDE
====================================================================

Shield means depositing into a privacy pool.

Typical flow:
1. Choose the pool you want.
2. Enter the amount.
3. Approve if the token needs approval.
4. Submit the shield transaction.
5. Wait for confirmation.
6. Save the resulting note right away.

Tips:
- Keep the note title or label readable.
- Verify the asset type before submitting.
- Make sure you have enough balance for gas and amount.
- If you are shielding DEX, check approval status before depositing.

====================================================================
5) LOCAL NOTES GUIDE
====================================================================

Your local Boxpool notes are the most important part of the workflow.

What notes are for:
- They prove you participated in a privacy pool deposit.
- They contain the secrets needed to unshield later.
- They help track pending, ready, tracking-only, and hidden entries.

How to use notes safely:
- Copy the note to a secure place.
- Download a JSON backup.
- Do not assume the browser cache is enough.
- If you switch devices, import the note backup.
- If you see tracking-only or incomplete states, treat the note with care.

Important:
- A note with missing or mismatched data may not be usable for proof.
- Partial unshield flows may create remainder notes.
- Always keep the updated remainder note after a partial withdraw.

====================================================================
6) PERSISTENT VS SESSION NOTE STORAGE
====================================================================

Session storage:
- Default mode
- Notes live in the current browser session only
- Best for temporary use or testing

Encrypted persistent storage:
- Saves encrypted notes in local storage
- Requires a password unlock
- Best for continued use across browser restarts

Security reality:
- Encryption at rest helps, but it does not remove endpoint risk.
- If the browser session or device is compromised while unlocked,
  attackers may still capture note material.
- Persistence improves convenience, not absolute safety.

Recommended approach:
- Use session mode while testing
- Use persistent mode only when you are ready to save notes safely
- Always keep an external backup regardless of mode
- Keep large-value notes out of normal browsing environments

====================================================================
7) UNSHIELD MODES EXPLAINED
====================================================================

Boxpool supports multiple unshield modes.

relay mode:
- The request is routed through the relayer path
- Good when you want a relayed withdrawal flow
- Check relay settings and fee limits
- Best when you want the standard Boxpool relay path

relayCustom mode:
- Same basic relay flow, but you can specify the relayer URL
- Useful if you want to point to a custom relayer endpoint
- Make sure the URL is trusted and reachable

direct mode:
- The recipient is auto-filled with your connected wallet
- Good for straightforward wallet-based withdrawal
- Simpler than manual routing

wallet mode:
- Direct on-chain execution with wallet signing
- Lets you use your connected wallet or a manual signer setup
- Good for users who want more explicit control

private key signer mode:
- Advanced mode for manual private-key signing
- High risk if used carelessly
- Only use a temporary or dedicated key
- Never paste a long-term wallet key unless you fully understand the risk

====================================================================
8) HOW TO PICK AN UNSHIELD MODE
====================================================================

Choose relay if:
- You want the standard relayer flow
- You are following the normal Boxpool withdrawal path

Choose relayCustom if:
- You want to test or use a custom relayer URL
- You know exactly which relay endpoint you trust

Choose direct if:
- You want the recipient to be your connected wallet
- You want the simplest user experience

Choose wallet if:
- You prefer on-chain signing with your wallet
- You want more manual control over the execution path

Choose private key signer only if:
- You know why you need it
- You understand the security risks
- You are using a safe temporary key

====================================================================
9) HOW TO UNSHIELD SAFELY
====================================================================

1. Select a proof-ready note.
2. Enter or confirm the recipient.
3. Set the amount.
4. Review the payload carefully.
5. Generate the proof.
6. Back up the remainder note if the flow creates one.
7. Submit only after verifying everything.

If the note is incomplete:
- Recover the metadata first if possible
- Sync the note from chain if needed
- Do not force a proof on a broken note

If the note is tracking-only:
- It is not a normal proof-ready note
- Treat it as history/audit data unless the app says it is ready

====================================================================
10) GOOD HABITS
====================================================================

- Double-check the amount before submitting.
- Keep recipient addresses accurate.
- Save backups before doing partial unshields.
- Use the note import tools only on trusted JSON.
- Keep your relayer settings documented if you use custom mode.
- If something looks wrong, stop and verify before continuing.

====================================================================
11) TROUBLESHOOTING
====================================================================

If shield fails:
- Check wallet balance
- Check token approval
- Confirm the chain is correct
- Retry after gas and RPC checks

If unshield proof fails:
- Make sure the note is proof-ready
- Confirm the recipient and amount
- Sync the note if chain state changed
- Try a different unshield mode if appropriate

If notes disappear:
- Check whether you are in session-only mode
- Look for hidden notes
- Restore from your downloaded backup
- Unlock persisted notes if encryption is enabled

====================================================================
12) FINAL WARNING
====================================================================

Boxpool is only useful if the note is kept safe.
Shielding without backing up the note is a common way to lose access to
your own funds later.

Save the note.
Download the backup.
Keep a second copy if the amount matters.

That is the main rule.