Document the SAC and CAP-67 asset event schema

[kalepail]

Finding

The generic token-interface event documentation does not call out the current
SAC/CAP-67 exception. A reader can reasonably conclude that a direct SAC
transfer has the same three topics as a custom SEP-41 transfer, but current
host source and tests append the SEP-11 asset string to direct SAC and Classic
unified events.

Evidence

Additional recorded evidence:

• token-interface page presents generic SEP-41 transfer/mint topic shapes
• CAP-0067 and released/current rs-soroban-env append sep0011_asset to direct SAC transfer/mint events
• current host test_transfer_with_issuer passed and asserts the asset-appended shape

Recommendation

Add an event-schema table distinguishing custom SEP-41 from current SAC/CAP-67
transfer, mint, burn, and clawback events. Explain that direct SAC and Classic
unified events share the SAC schema and require transaction/operation metadata
to distinguish their path. Link the payment/event-indexing guidance and include
one tested fixture.

Source Record

This was found by the downstream Raven eval/improvements loop and recorded as sd-018 (stellar-docs, discovered 2026-07-11).

Public source record: improvements/stellar-docs/sd-018-sac-cap67-event-schema-gap.md

Immutable source snapshot: bbb0d4f55527

Resolution Handoff

When a fix is deployed, please link the resolving issue or PR to the source record above and notify Raven through:

https://github.com/kalepail/stellar-raven/issues/new?template=upstream-improvement-ready.yml&title=%5Bupstream-ready%5D%20sd-018%3A%20

Include the finding id, resolving issue/PR, deployed version or timestamp, and the smallest live recheck. Raven independently verifies the upstream surface before changing the finding to fixed-upstream; issue closure or a merged PR alone is not treated as proof. After a distinct reviewer repeats the live check, the active finding is retired to Raven's resolved ledger while the immutable snapshot remains available.

[kalepail]

Implementation correction from independent source verification:

• transfer has 4 topics; mint, burn, and clawback have 3 each, with the asset last;
• muxed transfer/mint destinations change the data payload to {amount, to_muxed_id};
• the trailing asset topic predates CAP-67; CAP-67 removed the admin topic from mint/clawback, added muxed payloads, and unified Classic events;
• SAC transfer's fourth topic already appears in the payment guide, so new prose should cross-link it;
• stale mint/clawback comments also remain in rs-soroban-sdk/token.rs, so a companion SDK fix prevents re-drift.

Audit evidence: https://gist.githubusercontent.com/ElliotFriend/3b3641b929b4408a834b85bcb4e75449/raw/a90e6b453ee3505ef2525b4428eaa75752e3ae08/raven-audit-rebuttal.md

[ElliotFriend]

Verified against rs-soroban-env, with a couple of corrections to the original framing:

• Only the SAC transfer event carries 4 topics (the SEP-11 asset string as the trailing topic); mint/burn/clawback have 3.
• That asset topic actually predates CAP-67 — CAP-67 removed the admin topic from clawback.
• "Documented nowhere" isn't quite right: send-and-receive-payments.mdx already decodes topics[3] for SAC.

The real catch: the wrong doc-comments (stellar-asset-contract.mdx mint/clawback shapes) exist verbatim upstream in rs-soroban-sdk token.rs, so a docs-only fix here would re-drift on the next regen. This needs a docs change plus a companion rs-soroban-sdk PR to the token.rs doc-comments.

Leaving open pending the cross-repo companion; the docs-side schema-comparison table is ready to draft once that's lined up.

[kalepail]

Thanks — your corrections match what we found on re-verification, and I'd rather have the record right than be right. Confirming all three: 4 topics is transfer-only, the trailing SEP-11 asset topic predates CAP-67 (what CAP-67 removed was the admin topic), and send-and-receive-payments.mdx does already decode topics[3], so "documented nowhere" was too strong.

Strong agreement on the real catch: a docs-only fix re-drifts while the SDK carries the stale shapes. I've filed that against the SDK as stellar/rs-soroban-sdk#1955.

One calibration note from reading soroban-sdk/src/token.rs on main today, in case it narrows the work: within StellarAssetInterface, clawback is the one that still carries the removed admin topic (and labels its address topic to although the parameter is from); mint and set_authorized are missing the trailing sep0011_asset topic but are otherwise fine. The generic TokenInterface needs no change — its transfer already documents the CAP-67 muxed data map.