A frend in-world pointed me towards the SL forums today, and an interesting post from Kelly Linden on upcoming functionality which will allow scripts that pay out L$ to determine whether or not the transfer is successful, fails or is refused by the recipients.
The new functions are called llTransferLindenDollars and transaction_result.
Kelly Linden provides further information:
key llTransferLindenDollars(key id, integer amount)
- Attempts to transfer amount of L$ from the owner of the object to id.
- Requires PERMISSION_DEBIT.
- Returns a key used in a matching transaction_result event for the success or failure of the transfer.
transaction_result(key transaction_id, integer success, string data)
- LSL event triggered from an llTransfer* call (currently only llTransferLindenDollars).
- transaction_id matches the return value of the llTransfer call. If the transaction was successful the id will match the transaction id shown in the transaction history on secondlife.com.
- success is TRUE if the transfer succeeded otherwise FALSE.
- data will contain a CSV of destination id and amount transferred on success and an error tag on failure.
Kelly further explains:
llTransferLindenDollars has all the exact same limitations and restrictions as llGiveMoney – no more and no less. The only difference is that the result of that transaction is routed back to the script when llTransferLindenDollars is used.
L$ transactions in Second Life are managed by a service internally termed “L$ API”. This includes llGiveMoney and direct agent to agent transfers – and anything else that transfers L$. The new function doesn’t actually “pull the transaction data from the LL servers”, it just passes back the results from using the L$ API.
It is true that this service operates on HTTPS hence the possibility of it giving an “HTTP status code other than 200”. This is expected to be extremely rare. As for the incident today on the beta regions: in order to reproduce this error (and ensure it works as expected) QA forced a configuration change such that this particular region host believed the L$ API existed at a nonsense address. Resetting the configuration to default fixed it of course.
To be extra clear:
- There are no cases where llTransferLindenDollars could succeed when llGiveMoney would fail.
- There are no cases where llTransferLindenDollars could fail when llGiveMoney would succeed.
There are some rare edge cases, mostly relating to LSL limitations:
- LSL scripts do not process more than one event at a time. If the script gets reset, the object taken, or the region restarted while the transaction_result is pending in a queue (because the script is busy in another event) then the result may get lost. This risk can be mitigated by using scripts that are mostly idle while waiting for the transaction_result event. This is not unique to the new features but applies to all events in LSL.
- LSL scripts have a max event queue size of 64. If the event queue is full new transaction_result events will get dropped. This risk can be mitigated by ensuring the script handling the transaction_result does not build up a queue of events. This is not unique to the new features but applies to all events in LSL.
- The only script in an object which will get a transaction_result event is the script that called llTransferLindenDollars. This is similar to how the http_request event works.
You can follow / join the discussion on these functions in the SL forums.