Money Adapter

By Snoopy Pfeffer - Posted on 31 December 2013

Overview

Dreamland Metaverse offers it's customer an unique tool to implement a local grid currency. The Money Adapter OpenSim solution can be used to implement local "play money" as well as grid currencies that can be exchanged with a real world currency via PayPal, using a fixed exchange rate.

Never before it was so easy to implement your own grid currency!

The Money Adapter is a complete solution and does not require any additional software or web development on your side, even for in-world currencies that can be exchanged with a real world currency. We provide all that is needed for a fully functioning grid currency.

All money related functionality of the viewer is supported, including buying in-world currency and paying upload or group creation fees. When a user does not have enough in-world currency to buy an object or land, he automatically gets an offer to exchange money to be able to make that payment.

On top of this viewer functionality we have implemented procedures and tools for selling in-world currency and to allow users to view their money transaction records. Additionally the grid owner can easily "print" in-world currency, using the standard buy currency functionality of the viewer, without having to use any real world currency.

Additional Functionality

Users can view their money transaction report by simply typing "/1 money report" in their viewer chat window. Afterwards they receive their money transaction report of the last 31 days as email. All money transactions are shown, including the kind of transaction, time, amount as well as user and object involved.

Selling in-world currency is implemented as paying in-world money to a defined bank account of your OpenSim grid. The grid owner pays out such amounts as real world currency on a regular basis. Such payments are done via PayPal, to the email address of the OpenSim user account.

The so called "CashOutPage" tool helps the grid owner to easily do this task with just some clicks. The grid owner is sent a list of money exchange requests to real world currency, usually once each day. This way the grid owner always keeps control of all outgoing money flows in real world currency.

Defining Your Grid Currency

The grid owner can define the following parameters, related to exchanging money:

Grid currency symbol (i.e. MY$).
Starting balance of every new user.
Bank user account received for uploading as well as group creation fees. Also used as recipient of in-world money to exchange that money to real world currency.
PayPal exchange enabled yes or no? If yes, the following additional information is required:
Fixed exchange rate with real world currency (most often OS$ 100 = US$ 1.00).
Real world currency symbol (usually USD; especially for old 1.x based viewers only supporting USD).
Per transaction and percentage based fees for exchanging real world currency to virtual currency and vice versa (separately for each direction). Usually at least the grid owner's PayPal fees should be covered.
PayPal account (email address) used for all transactions involving real world currency.
Minimum amounts to exchange real world to virtual world currency and vice versa (separately for each direction).

Supported In-World Payments

The kinds of payments the Money Adapter supports are:

Give money
Pay object
Buy object
Buy land
Object pays
Asset upload charges
Group creation charges
Buy or Sell currency (only if PayPal option is enabled)
All LSL money functions and events, including llGiveMoney

Limitations

The Money Adapter requires that users have the Helper URI properly defined for the local grid. That usually is not the case for HyperGrid visitors, with the consequence that such visitors cannot do payments. In such cases it is a good idea that shop owners recommend users to register a local user account.

Similar issues are the case for public grids, where the region owners cannot define or change the Helper URI. In general such grids cannot support multiple true in-world currencies that are closely integrated with the corresponding viewer functionality.

An alternative money solution for such cases is the PayPal money module that we also offer. The PayPal money module does require just a basic Helper URI, providing very basic in-world currency support. It works in public grids as well as for HyperGrid visitors, because users directly use US$ cents via PayPal.

Technical Solution

The Money Adapter solution of Dreamland Metaverse consists of a closed source Money Adapter OpenSim module and an open source Money Server.

The Money Adapter OpenSim module hides the complexity of the OpenSim internal processing of financial transactions. It allows a very much simplyfied implementation of OpenSim in-world currencies and provides a standard interface to Money Servers.

The core of the virtual world currency is the Money Server. The Money Server stores the balances of all users and it's simple interface supports all kinds of OpenSim money transactions.

The money server can be located on your own server or it can be hosted by us (for free). This gives you the freedom to choose how closely you want to control your own grid currency. Beside that a locally hosted Money Server allows you to extend the money related functionality and to integrate it into your grid web site.

The following sections are just interesting for you, if you intend to run a Money Server on your own server. We also offer Money Servers hosted on our servers for free. This is the best option, if you do not need a locally hosted Money Server.

Money Server

We provide a fully working, open source copy of the Money Servers here. This allows you to run your Money Server on your own server and to make any custom modifications you want, i.e to add money related functionality to your grid web site.

The Money Server requires Apache, MySQL and PHP and consists of a database and a set of PHP scripts working on a MySQL database. It provides no user interface and you have to use database SQL queries to modify the database contents, for example to give some avatars some starting balance. - If you choose a hosted Money Server, we configure the starting balance for you.

A README file describes how to setup the database and the PHP scripts on your local web server (database and webroot subfolders). Especially change the config.php script to your needs. A file TransactionTypes.txt lists the transaction types you receive (see MoneyTransfer interface function). In the file OpenSim.ini.include you can see what we can configure for your OpenSim regions.

OpenSim Configuration

OpenSim needs to be configured such that your grid uses the Money Adapter and finds your Money Server. If you host the Money Server yourself, it is necessary that you give us the information shown in the OpenSim.ini.include file. Especially important is the following information:

;; Money server URI (http or https) and password
MoneyServerURI = https://127.0.0.1/money/
MoneyServerPassword = password

;; Set this value to the UUID of central bank avatar
BankAccount = 00000000-0000-0000-0000-000000000000

The bank user account is required, if any fee payments are used or if users can change money back to a real world currency. Only uploading fees or group creation fees are supported at the moment. Please tell us, if you want these fees enabled for your OpenSim grid.

The Money Server PHP scripts have to be installed in a web folder accessible via SSL (HTTP-S). Beside that a safe password has to be shared. High security is essential, especially when your grid currency can be exchanged with real world currencies.

In the files config.php and OpenSim.ini.include you can find all settings you need to provide us to customize the Money Adapter to your needs (see list in the "Defining Your Grid Currency" section above).

Appendix: Money Server Protocol

This section gives a short introduction to the Money Server protocol implemented by the Money Adapter OpenSim module. This technical information is just interesting for you, if you intend to modify a locally installed Money Server.

It is necessary that your Money Server knows in which region a user is. The reason is that you need to send change notifications, if the balance of a user changes. In the scripts MoneyTransfer.php and ModifyBalance.php you can see how these change notifications are sent to OpenSim regions (balance_changed notifications). In case a region does not respond, that region registration database entry gets deleted. The Money Adapter automatically sends Enter and Leave notifications to your Money Server, so that it always knows where to find which user.

https://<money server>/money/Enter.php?PW=<money pw>&AgentID=<Agent UUID>&URI=<OpenSim URI>

https://<money server>/money/Leave.php?PW=<money pw>&AgentID=<Agent UUID>&URI=<OpenSim URI>

With GetBalance the Money Adapter fetches the current account balance from your Money Server (returns an empty string in case of an error):

https://<money server>/money/GetBalance.php?PW=<money pw>&AgentID=<Agent UUID>

The main interface function to perform money transfers is MoneyTransfer. It uses a database transaction for the critical balance changes. For transaction type codes see file TransactionTypes.txt.

https://<money server>/money/MoneyTransfer.php?PW=<money pw>&ObjectID=<Object UUID>&FromID=<From Agent UUID>&ToID=<To Agent UUID>&Amount=<Amount>&Type=<Transaction Type>

The second main interface function is ModifyBalance to add or substract a given amount from the user balance. This interface function is used whenever a user buys or sells in-world currency. It uses a database transaction for the critical balance changes.

https://<money server>/money/ModifyBalance.php?PW=<money pw>&AgentID=<Agent UUID>&Amount=<Amount>

GetBalance, MoneyTransfer and ModifyBalance automatically create new table entries for unknown users and groups in the Balances table, with the starting balance zero.

All transactions are stored in a Transactions database table. The following Transaction Types are currently used:

None = 0 // General Charge
GroupCreate = 1002 // Group Creation Charge
UploadCharge = 1101 // Upload Charge
ObjectSale = 5000 // Buy Object
Gift = 5001 // Give Money
PayObject = 5008 // Pay Object
ObjectPays = 5009 // Object Pays
BuyLand = 5013 // Buy Land
LindenAdjustment = 9000 // Bought or Sold Currency

Appendix: Money Server Tools

The following Money Server interface functions provide tools, so that users can view their money transaction report and that grid owners easily can exchange in-world currency to real world currency.

The interface function MoneyReport creates a money transaction report and show it as HTML output or sends it to an optionally provided email address. It is also possible the specify an optional time parameter (Unix timestamp) to just show transactions after that given time. By default the transactions of the last 31 days are shown.

https://<money server>/money/MoneyReport.php?PW=<money pw>&AgentID=<Agent UUID>&Time=<Unix Timestamp>&Email=<Email>

The interface function CashOutPage creates a page that allows the grid owner to easily pay out real world money via PayPal, for in-world money that was sent to the grid bank user account. That page is shown as output or sent to an optionally provided email address. It is also possible the specify an optional time parameter (Unix timestamp) to just show transactions after that given time. By default the transactions of the last day plus 10 minutes are shown.

https://<money server>/money/CashOutPage.php?PW=<money pw>&Time=<Unix Timestamp>&Email=<Email>

If you have questions how to use the Money Adapter solution for your own grid please contact us.