Problem
pay() and pay_many() take (from, id, token, amount) and emit SplitPaid { id, token, amount }. There is nowhere to attach an external identifier to a payment.
Why this matters
The product's stated use cases are marketplace sales, royalties, and team payouts. Every one of those needs to answer "which order/invoice/period was this payment for?" Right now an integrator paying a marketplace split for order A-1234 has no way to tag it. Their options are all bad:
- Match on
(amount, ledger) heuristically, which breaks the moment two orders have the same total.
- Deploy one split per order, which is absurd for storage and defeats reusable routing.
- Keep the mapping in their own database keyed by tx hash, which they can only learn after submission and which makes the on-chain record useless on its own.
For a payment rail, an unreferenced payment is hard to reconcile, and reconciliation is the whole job on the merchant's side.
Suggested fix
Add an optional reference to the pay path, for example reference: Option<BytesN<32>> (a hash or a padded external id), carried through into the SplitPaid event. Making it a topic would allow filtering by reference in getEvents, at the cost of a topic slot.
Consider whether deposit() should take one too, so escrowed funds can be attributed on the way in as well.
Note: Stellar classic has a transaction memo, but it is per-transaction, not per-operation, so it cannot tag individual splits inside a pay_many batch. That is a good argument for putting the reference in the contract call rather than relying on memos.
Acceptance criteria
pay and pay_many accept an optional reference; pay_many allows a distinct reference per split in the batch.- The reference appears in the emitted event and is picked up by the indexer and
export-csv.mjs.
- Omitting it is free and fully backward compatible for existing callers.
- The SDK exposes it as an optional argument.
- Tests cover: with reference, without reference, and per-split references in a batch.
Problem
pay()andpay_many()take(from, id, token, amount)and emitSplitPaid { id, token, amount }. There is nowhere to attach an external identifier to a payment.Why this matters
The product's stated use cases are marketplace sales, royalties, and team payouts. Every one of those needs to answer "which order/invoice/period was this payment for?" Right now an integrator paying a marketplace split for order
A-1234has no way to tag it. Their options are all bad:(amount, ledger)heuristically, which breaks the moment two orders have the same total.For a payment rail, an unreferenced payment is hard to reconcile, and reconciliation is the whole job on the merchant's side.
Suggested fix
Add an optional reference to the pay path, for example
reference: Option<BytesN<32>>(a hash or a padded external id), carried through into theSplitPaidevent. Making it a topic would allow filtering by reference ingetEvents, at the cost of a topic slot.Consider whether
deposit()should take one too, so escrowed funds can be attributed on the way in as well.Note: Stellar classic has a transaction memo, but it is per-transaction, not per-operation, so it cannot tag individual splits inside a
pay_manybatch. That is a good argument for putting the reference in the contract call rather than relying on memos.Acceptance criteria
payandpay_manyaccept an optional reference;pay_manyallows a distinct reference per split in the batch.export-csv.mjs.