Messages, files, ⚡payments, invites/pins, channels + pay-to-post, anchoring · content/guides/using-chat.md

Using Chat — messages, files, ⚡payments, channels

The messenger where the money rides inside the envelope. Every command below was run against the live relay on 2026-09-12.

✓ verified 2026-09-12 — topup → send → pay → recv round-trip (alice→bob: message + ⚡0.25 card, r_d90476b7ac), conversation anchored (tx 2YdPGUwV…) and verify-convo ✔. Invite/pin flow verified (invite --as gsg, fingerprint GKA5-JSWK-ZE). Channels via qalpub (:8832, live).

What you need

• An identity (getting-started, two minutes).
• The other person's handle (weak) or their signed invite link / QR (strong).
• The desktop wallet's Chat tab, or the CLI: python3 qalchat/qalchat.py ….

Steps

1. Add a person

Wallet: Contacts ▸ Add a person ▸ type their handle (wallet shows their qoll-code — confirm it out-of-band, e.g. on a call) or paste their qalchat://invite?… link / scan the QR (signed, verified before pinning — the strong path).

python3 qalchat/qalchat.py invite --as gsg        # your signed link + QR
python3 qalchat/qalchat.py accept "<invite-uri>"  # verify + pin their key
python3 qalchat/qalchat.py contacts --as gsg      # codes + fingerprints + pin source

Pin = locked-in trust: their key is remembered, and if it ever changes, sending stops with a red warning — substitution is treated as an attack, never silently accepted.

2. Send and receive

Wallet: pick the conversation, type, Enter. 📎 opens the attach menu: 📷 image · 📄 file · ⚡ attach Qals · 🔒 locked content. Find-in-conversation, mute, unread badges, day separators, ticks (✓ delivered → ⚓ anchored).

python3 qalchat/qalchat.py send bob "hello" --as alice
python3 qalchat/qalchat.py recv --as bob          # fetch + decrypt
python3 qalchat/qalchat.py chat bob --as alice    # live interactive session

What success looks like: on bob's side, [alice → me] #3 hello. The relay in the middle held only sealed envelopes — it delivered, it never read.

3. Pay inside the conversation

python3 qalchat/qalchat.py pay bob 25 "latte" --as alice
# → transfer ok: r_d90476b7ac 25c (0.25 B-QALS) → bob
# → payment message sealed into the conversation

Wallet: 📎 ▸ ⚡ Attach Qals ▸ amount (live doof equivalent shown) ▸ the gold chip rides your next message; or ⚡ Pay to send payment-only. What success looks like: a permanent gold ⚡ 0.25 B-QALS card in the thread with the settle id — money and message arrived together, and the receipt lives in the ledger. Daily caps apply (default AU$200/day per agent) — the ledger refuses over-cap, full stop.

4. Files

python3 qalchat/qalchat.py send-file bob report.pdf --as alice   # ≤8 MB, encrypted
python3 qalchat/qalchat.py recv-files --as bob                   # sha256-verified, auto-anchored
python3 qalchat/qalchat.py files --as bob                        # list + anchor receipts

Received files carry their anchor tx — a chain stamp proving the bytes you received are the bytes that were sent. In the wallet, files render inline (images) or as sha256 file cards.

5. Locked content (sell inside chat)

Wallet: 📎 ▸ 🔒 Locked content ▸ price + optional preview + file ▸ Seal & send. The peer sees a blurred card — "Unlock for 1.50 Qals" — payment goes through escrow, the key is re-wrapped to them alone, and the card flips open in place. Powered by qalpay's send-locked/buy-unlock protocol on qalpub escrow.

6. Channels and pay-to-post

Discord-model boards under Chat: browse the public index (topics, post counts, anchored-digest badges), post, thread, react.

python3 qalpub/qalchannels.py create general --topic "the daily"
python3 qalpub/qalchannels.py post general "hello channel"

Some channels charge to post — that is anti-spam plus creator earnings, not a chain fee (ground truth F18): spam now has to spend. Daily digests are Merkle-anchored, so channel history is tamper-evident.

7. Anchor a conversation (the receipts feature)

python3 qalchat/qalchat.py anchor bob --as alice       # Merkle root → Qalnet (prints tx)
python3 qalchat/qalchat.py verify-convo bob --as alice  # → ✔ verified against anchor

Turn a chat into court-grade evidence in two commands. The phone sees everything too: the qalbridge phone page shows transcripts and gold ⚡ cards (login-and-accounts §phone bridge).

What success looks like

• contacts lists your person with a fingerprint you confirmed by voice.
• A gold ⚡ card with a r_… id; balance moved on both sides.
• verify-convo prints ✔ against a Qalnet tx.

Troubleshooting

Companions: chat design (the crypto, honestly) · getting-started · using-the-wallet.