The OmiseGO eWallet is an Elixir application freely available for anyone who wishes to run a (local) ledger through a web interface.
The eWallet will later be plugged to a blockchain and connected to a decentralized exchange. All the eWallets will then become a federated network forming the top layer of the OMG network, allowing the exchange of any currency into any other in a transparent way.
In the rest of this document, a person or company setting up this eWallet is called a provider.
The OmiseGO eWallet and SDKs are still under heavy development, and therefore, in "beta". This means things might break or change suddenly. We are moving fast, and until the official release, we'd like to keep it that way.
Use at your own risk.
(Still, we will do our best to keep breaking changes to the minimum and notify when such events happen)
Do not expect to find anything related to blockchain integration yet. It will come, when it's ready.
- Introduction
- OmiseGO SDK Integration Diagram
- Sample Setup
- Getting Started
- Deploying the OmiseGO eWallet
- Coming Soon
- F.A.Q
- Going Further
- Contributing
- License
Stable: The latest stable release of the eWallet.
Current (a.k.a staging): The most up-to-date version of the eWallet. We work with this version every day, so things might break.
The URLs below are OmiseGO testing and sample eWallets. The eWallet is not a centralized service and no one should actually use those in production.
-
SDKs:
-
Sample Apps:
What is commonly called as the OmiseGO SDK is actually composed of a few different applications.
- eWallet: Currently only acting as local ledger (as opposed to a decentralized one), it will later on be plugged on a blockchain with minimal changes required for providers. The eWallet needs to be deployed on a server.
- Server and client SDKs: To simplify the communication with the eWallet, OmiseGO provides language-specific SDKs.
Currently, the easiest use-case to understand what the eWallet can do is to see it as a loyalty point ledger. Once the blockchain is plugged, those points will become actual tradable cryptocurrencies.
Here’s an overview of all the components and what needs to be integrated by a provider (and how):
OmiseGO has built a sample setup to demonstrate how the OmiseGO eWallet and the SDKs can be used. It is a simple t-shirt store allowing users to receive loyalty points when buying something. They can then use those loyalty points to get a discount.
The code and documentation are available in the following repositories:
The demo server applications have been deployed and are available at the following URLs:
The following section will get you up to speed on the eWallet and show you how to deploy it in local.
We provides a Docker image for quick installation at the omisego/ewallet repository on Docker Hub with the following tags:
latesttracks current (i.e. develop branch)stabletracks stable (i.e. master branch)
Additionally, all commits in develop and master branches are also built. It is highly recommended to pin the version to specific commit in anything that resembles production environment. An easiest way to get the Docker image running would be (assuming PostgreSQL is already setup):
$ docker run \
-e DATABASE_URL="postgresql://postgres@127.0.0.1:5432/ewallet" \
-e LOCAL_LEDGER_DATABASE_URL="postgresql://postgres@127.0.0.1:5432/local_ledger" \
-p 4000:4000 \
omisego/ewallet:latest
Then run docker exec <container-id> mix do ecto.create, ecto.migrate to setup the database.
If you don't want to set up everything from scratch with the instructions below, you can use Goban instead. Goban will generate a consistent development environment within a virtual machine for you without having to install the dependencies manually.
Once Goban is set up successfully, you can access your development environment by running the command vagrant ssh, then skip directly to Setting up.
Be sure to have the following applications installed and running on your machine.
-
PostgreSQL: PostgreSQL is used to store most of the data for the eWallet API and local ledger.
-
ImageMagick: ImageMagick is used to format images in the admin panel. Tested with version
> 7.0.7-22. -
Libsodium: Sodium is a new, easy-to-use software library for encryption, decryption, signatures, password hashing and more. It is used to hash and encrypt/decrypt sensitive data.
-
Elixir: Elixir is a dynamic, functional language designed for building scalable and maintainable applications.
-
Git: Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
Once you have installed the all the dependencies and they are running, it's time to pull the eWallet code. To do so, let's use git:
git clone https://github.com/omisego/ewallet && cd ./ewallet
Feel free to look around!
We now need to pull the Elixir dependencies:
mix deps.get
Then get the front-end dependencies:
(cd apps/admin_panel/assets/ && yarn install)
If you are setting up without Goban, you may need to set some environment variables before proceeding. You can use export ENV=value to set environment variables in the current session (or you can add them to whatever profile file you're using).
It is important to understand that the eWallet actually connects to two different databases. The first one, the local ledger database, is only used to store transactions, making it easier for audits. The second one contains, well, everything else.
In development, you should only have to set the DATABASE_URL and LOCAL_LEDGER_DATABASE_URL if your local PostgreSQL installation requires authentication.
DATABASE_URL: The URL where the main database can be accessed. Defaults topostgres://localhost/ewallet_devindev,postgres://localhost/ewallet_testintest.LOCAL_LEDGER_DATABASE_URL: The URL where the ledger database can be accessed. Defaults topostgres://localhost/local_ledger_devindev,postgres://localhost/local_ledger_testintest.
The ewallet_dev and local_ledger_dev don't need to be created beforehand as long as the database URLs contain credentials allowing this kind of operations.
In some cases, you might also want to customize the following ones, depending on your development setup:
BASE_URL: The URL where the application can be accessed. Defaults tohttp://localhost:4000.PORT: The internal listening port for the application. Default to4000.
To learn more about all the environment variables available for production deployments (or if you want to get fancy in local), checkout this doc.
Before we start the application, let's try running the tests. Create the test databases:
MIX_ENV=test mix do ecto.create, ecto.migrate
Or if you're using specific database URLs:
MIX_ENV=test DATABASE_URL=postgres://localhost/ewallet_test_db LOCAL_LEDGER_DATABASE_URL=postgres://localhost/local_ledger_test_db mix do ecto.create, ecto.migrate
If you don't want to do that, you can always search & replace the default values in the config files, but only do that in development to give it a try - we really don't recommend changing the code that way for production setups.
Then, let's run the tests:
mix test
Or:
DATABASE_URL=postgres://localhost/ewallet_test_db LOCAL_LEDGER_DATABASE_URL=postgres://localhost/local_ledger_test_db mix test
==> local_ledger_db
Finished in 0.5 seconds
57 tests, 0 failures
==> ewallet_db
Finished in 2.3 seconds
249 tests, 0 failures
==> local_ledger
Finished in 0.9 seconds
24 tests, 0 failures
==> ewallet
Finished in 3.4 seconds
141 tests, 0 failures
==> admin_api
Finished in 4.4 seconds
184 tests, 0 failures
==> ewallet_api
Finished in 4.5 seconds
134 tests, 0 failures
All the tests should pass. If some tests are failing, double-check you have install all the dependencies. If you keep getting the failures, you can get in touch with us on Rocket!
If all the tests passed, we can create the development databases:
mix do ecto.create, ecto.migrate
Everything is in place and we can now run the seeds to populate the eWallet database with some initial data:
mix seed
Note: The command above seeds the minimum amount of data to get the environment up and running. To play in development environment with some sample data, run mix seed --sample instead.
Time to start the application!
mix omg.server
Navigate to http://localhost:4000/api in your browser and you should see the following JSON representation popping up:
{
"success": true,
"services": {
"local_ledger": true,
"ewallet": true
}
}
You can also access the Admin Panel web interface via http://localhost:4000/admin using
the credentials provided during the seed.
All set! Start playing around with the API using the Swagger UI below to learn more about the available endpoints. Enjoy!
- Admin API: http://localhost:4000/admin/api/docs
- eWallet API: http://localhost:4000/api/docs
Here are some steps to get you started with the fun, they can all be performed by accessing the Swagger UI linked above:
- In the Admin API, configure the authentication at the top using the keys generated in the seeding step.
- Log yourself in and get the returned authentication token. In case you're getting an invalid auth scheme, double check that you're using
OMGAdminwith the base64 encoded version ofAPI_KEY_ID:API_KEY(with no\n, some programming languages add them). - Configure the user authentication using the authentication token you've received in the previous step.
- Create a minted token using
/minted_token.create. You can specify the optionalamountparameter to do an initial minting. - After that you're ready to start messing around with the eWallet API. You can create yourself a user using one of the server calls and credit/debit tokens!
If Swagger UI is not enough, you can start communicating with the web APIs using any programming language of your choice, either by using the HTTP-RPC endpoints directly or by using one of the available SDKs.
If you wish to use the HTTP-RPC web APIs directly, here are the OpenAPI specifications containing all the available endpoints and how to interact with them. You can access those interactive documentations on any running eWallet application, including the ones you deploy yourself! The eWallet API docs live under /api/docs and the Admin API ones under /admin/api/docs.
When using the eWallet API, be sure to have /api at the end of your base URL (e.g. https://yourdomain.com/api). For the Admin API, it should include /admin/api (e.g. https://yourdomain.com/admin/api).
To implement the sensitive calls in your server-side applications (such as crediting or debiting tokens from/to a user), the following SDKs are available:
For client-side applications (non-sensitive calls), the following SDKs are available:
If none of the current SDKs matches your needs, you can create it! Get in touch with us on Rocket and let us know. We'll be happy to help you implement it and, if your SDK meets our standards, support it as one of our official SDK.
OmiseGO offers hosting solutions for the OmiseGO SDK. Get in touch if you're interested.
Deploying the OmiseGO SDK can be done on any infrastructure. For security reasons, it is recommended to run the applications on one server and the databases on a different one.
More information about deployment will be available soon.
In this section, we will be sharing some of the next features the OmiseGO team will be working on.
- Better environment variables management for
testanddevenvironments. - Integrate the Admin Panel in the eWallet.
- Finalize the transaction requests mechanism allowing QR code transfers.
- Re-design and finalize the first version of the Admin Panel.
- Implement the Request Logger sub-app for easier logging and debugging.
- Refactor and split the factories files. Make smarter use of them throughout the tests.
- Refactor and unify the test helpers for minting.
- ...
Sure! You can deploy it on a server (or run it locally) and start using it as a ledger. Refer to the getting started section for more information.
When it's ready :) Feel free to follow the progress through PRs, issues and our monthly updates for more information.
Of course! Check out our contribution guidelines to get started.
We decided to stay as protocol-agnostic as possible and not follow HTTP conventions. Therefore, the web APIs only allows the POST method and returns 200 or 500 codes with custom representations and errors.
Each provider is responsible for running its own version of the eWallet. To get started, we offer hosting solutions but the long term goal is to have a federated network of eWallets running on top of a decentralized blockchain with no centralization.
More questions? Get in touch with us on Rocket Chat!
Here are some resources if you want to learn more about how the eWallet works.
- All ENV needed to run the eWallet
- Integration Responsibilities
- eWallet Entites
- eWallet Components
- A closer look at balances
See how you can help.
The OmiseGO eWallet is released under the Apache License.