Upcoming LSL feature: llTransferLindenDollars and transction_result

[Kelly Linden]

An upcoming server maintenance project is going to include some new functionality for LSL. This functionality is designed to allow scripts which pay out L$ to determine the success of that transfer.

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. 

Error Tags:

This is not an exhaustive list and it is possible these will change over time.

• LINDENDOLLAR_ENTITYDOESNOTEXIST - The destination UUID is not a valid agent.
• LINDENDOLLAR_INSUFFICIENTFUNDS - The source agent does not have enough L$ for the transfer
• INVALID_AGENT - Destination agent is not a valid UUID
• INVALID_AMOUNT - Amount is <= 0
• THROTTLED - The scripted L$ throttle was hit for this object owner.
• MISSING_PERMISSION_DEBIT - The script does not have debit permission
• GROUP_OWNED - The object is group owned and can't give money
• TRANSFERS_DISABLED - L$ transfers are disabled in the region
• SERVICE_ERROR - Received a non-200 http result from L$ API.

If you would like to try this feature out it is currently active on the channel DRTSIM-111 on regions Bethel, Fortuna and Sandbox Wanderton on Aditi.

[Honza Noyes]

Hey, just tested it in Sandbox Wanderton and Bethel, the function returns:

key transaction_id = 4a84ea3a-e3dd-49f5-3b88-9e83a97ae393
integer success = 0
string data = SERVICE_ERROR

[12:11] An internal error prevented us from properly updating your viewer. The L$ balance or parcel holdings displayed in your viewer may not reflect your actual balance on the servers.

[Kelly Linden]

Sorry about that Honza. This was a result of internal testing verifying some of the error codes. I have fixed the host and it should now be working for me.

One more note: we are planning on deploying a new version this afternoon sometime to pick up a fix unrelated to this feature.

Thanks for jumping in and trying it out!

[Honza Noyes]

So since this feature uses http to pull the transaction data from the LL servers, what kind of limits does it have? As in, is it limited by the count of HTTP requests or the llGiveMoney limit applies?

[Kelly Linden]

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.

Technical details:

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.

Hopefully that helps clarify things a little.

[Honza Noyes]

Thanks for the info Kelly.

[Prokofy Neva]

Hi,

What is the definition of a "valid agent" in the SL system?

Is it a person whose account is in good standing and is in the People List?

Example: I have an oldbie tenant who has content for sale on a property and even though he disappeared for some reason from the People list, i.e. not for a ban but because he may not have paid his bill or something, I'm assuming that he could come back, reactivate his account, and his content sales will still show in his account.

Or will this defeat that option?

[Void Singer]

valid agent is a key that is tied to an account, but not keys that are tied to other resources, or unassigned

[Cerise Sorbet]

---

Kelly Linden wrote:

• LSL event triggered from an
  llTransfer*
  call (currently only
  llTransferLindenDollars
  ).

---

That asterisk is such a tease. >.>

[Honza Noyes]

So far it works flawlessly.

[JB Hancroft]

Hi Kelly,

Can you please add some detail about this limit, as mentioned:

   "THROTTLED - The scripted L$ throttle was hit for this object owner."

thanks,

- JB

[Honza Noyes]

Since it is going to have same limitations as llGiveMoney, I suppose it means:

"Use is limited to 30 payments in a 30 second interval for all scripts owned by that resident on a region. Sustained overage will produce a script error and halt payments while the rate remains excessive. Historically, faster payments have failed intermittently."

[Mycroft Mesmeriser]

.

.

Thank you Kelly and LL. Nice work.

.

.

[Kelly Linden]

---

Honza Noyes wrote:

Since it is going to have same limitations as

llGiveMoney

, I suppose it means:

"Use is limited to 30 payments in a 30 second interval for all scripts owned by that resident on a region. Sustained overage will produce a script error and halt payments while the rate remains excessive. Historically, faster payments have failed intermittently."

---

This is correct. Additionally it should be noted that llGiveMoney and llTransferLindenDollars share the same throttle count. 20 of one and 15 of another under 30 seconds will trigger the throttle.

[Honza Noyes]

Kelly, is there any ETA of this feature to the main grid?

[Ray Silent]

Great news, thank you LL! We waited for that so much!

Would it be more type safe to send a "list data" instead of "string data"?

Or just to unpack these values and make the handler longer:

transaction_result(key transaction_id, integer success, key destination_id, integer amount_transfered, integer error)

and to send 0 in error when there was no error. Or join success & error params this way:

transaction_result(key transaction_id, integer result, key destination_id, integer amount_transfered)

and to add result "SUCCESS"?

[Honza Noyes]

I think that this is rather more complicated... You can just simply do llCSV2List and done.. And I am also sure it has some purpose for future features like making our own transaction descriptions or something like that...

[Kelly Linden]

The event is designed to be pretty generic for any future transaction features we may add. If it was made very specific to L$ transactions then when some other transaction feature was added we would need a new event or it would feel hacky.

[Kelly Linden]

It is currently in internal testing. There is no ETA for when it will be on the main grid at this time.

[Honza Noyes]

 

• TRANSFERS_DISABLED - L$ transfers are disabled in the region

Does this mean that you can disable Linden$ transactions in certain regions? Or generally, how can this error occur?

[GummieBear]

Just a quick Q about this, great work By the way, as this results in a transaction id, will there eventually be a way via script or HTTP request to 'pull' and view a given transaction record? if this already exists please let me know as well.

 

Peace.

[Honza Noyes]

Yes, this indeed exists, it basically downloads the XML file from transaction history, but there is a problem that the XML gets cached for 15 minutes, so for up-to-date checks during those 15 minutes, you need to toggle between the past 30 days...

I am using similar system for my vendor system in-world (also uses web server - PHP - to grab the XML and parse it into CSV), it is quite efficient, but the llTransferLindenDollars will be the best solution. There were some links on the SL Forums and a sample, it's too late now, but I could possibly find those and send them to you tomorrow.

Or if you skilled enough with PHP, you could possibly grabb the data directly from http://secondlife.com which would be way more efficient than grabbing the XML.

[Vagabond Carter]

Good question Gummie, not sure myself. Reseach pulls up no simple way to do this So I've filled a jira on it.

 

https://jira.secondlife.com/browse/SVC-7465

[MB Robonaught]

Hi that'll be handy when available. I was wondering are there any plans on having a way to save multiple replies from the function in a text form instead of just memory? In memory that can really lag things bad if one is getting dozens of hits and even hit the cap for list storage

[Kelly Linden]

---

Honza Noyes wrote:

 

• TRANSFERS_DISABLED
  - L$ transfers are disabled in the region

Does this mean that you can disable Linden$ transactions in certain regions? Or generally, how can this error occur?

---

Historically it has been necessary to disable L$ transfers across the grid for grid stability reasons - mainly to reduce database load. It has been a few years since this was last done to my knoweldge and it is an extremely unlikely event.