Money Adapter
Overview
The Money Adapter OpenSim module allows grid owners to implement a simple money server, that supports all OpenSim money transactions. The supported kinds of payments are:
- User to user payments
- Pay object
- Buy object
- Buy land
- All LSL money functions and events, including llGiveMoney
The complexity of the OpenSim internal processing of financial transactions is hidden. The Money Adapter provides a simple interface to a Money Server, providing the protocol to implement an inworld currency. This can be a currency that can be exchanged to real currency or game currencies, or it is just used as inworld play money.
Money Server
Our customers that use the Money Adapter get a working example implementation of a simple Money Server. Usually Money Servers are hosted at our customers' premises. Based on this example implementation it is easy to customize the Money Server as need. This example is ready to be used as server for play money.
The Money Server example 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 SQL queries to modify the database contents, for example to give some avatars some starting balance for tests.
A README file describes how to setup the database and the PHP scripts on your 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 (MoneyTransfer). In the file OpenSim.ini.include you can see what we can configure for your OpenSim regions.
OpenSim Configuration
OpenSim needs to be configured to use the Money Adapter for your grid. It is necessary that you give us the following information (see bold text):
;; 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
;; Set this value to true to enable payments to groups
;GroupsEnabled = false
The money server PHP scripts have to be installed in a web folder only accessible via SSL (HTTP-S). Beside that a safe password has to be shared. High security is essential, especially when it is be possible to exchange your grid currency to real currencies.
Money Server Protocol
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 example script MoneyTransfer.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 (return 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.
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>
GetBalance and MoneyTransfer 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
The banking avatar is only required, if any fee payments are used. 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.
Just 4 PHP functions are required to implement a fully working Money Server for OpenSim grids. The complexity how OpenSim handles money transactions is hidden by the OpenSim Money Adapter that Dreamland Metaverse has implemented for their customers.
