FIN4Xplorer documentation¶
Welcome to the documentation of the FIN4Xplorer plattform.
The latest live version can be found at demo.finfour.net and more general information are available at finfour.net.
The basic idea is: anyone can create tokens and anyone can claim these tokens. Once a claim is made, the user has to provide proof that the associated positive action actually happened. Which proof or proofs these are, is decided by the token creator when designing the token. If all proofs on a claim are automatically (e.g. a location to be within a certain circle) or manually (e.g. someone involved in the action is asked to approve a photo) approved, the claimer gets an amount “minted” on that token. We say someone “gets tokens”, which basically means that that persons public address gets an entry in the balance-sheet on the respective token with a positive number.
Getting started¶
Technical infrastructure¶
FIN4Xplorer consists of two parts:
- Smart contracts that are deployed to the Ethereum blockchain. The entire functionality is in these smart contracts. Everything could also be done by interacting with them via a command line.
- A frontend or client in the form of a Web DApp that acts as an user interface for convenient interaction with said smart contracts. Web apps run directly in the browser, both on desktop computers and on smartphones. DApp stands for distributed app, meaning they connect to a blockchain.
Infrastructure, programming languages and frameworks used¶
We decided to use the Ethereum blockchain for now. It satisfies our requirements of an open-source and public blockchain that supports smart contracts. Furthermore it is used widely these days and therefore plenty support resources are available.
The smart contracts are written in Solidity and we deploy them via truffle to the Rinkeby test network.
Rinkeby is one of a few Ethereum test networks and behaves similar to the main network. The difference is, that Ether, the “currency” used to pay for transactions, is not worth “real” money. On the main network Ether has to be earned via mining or bought on trading plattforms. On Rinkeby it can be requested from “faucets” for free, see section Getting Ether.
During development we use Ganache from truffle locally to simulate an Ethereum blockchain.
For storing media files that certain proof types require, we use IPFS via the Infura gateway.
As digital wallet to connect desktop or mobile browsers to the Ethereum network we use MetaMask, more about that in the following section Digital Wallet.
The frontend is a React app that uses drizzle from truffle to connect to the smart contracts on the Ethereum blockchain. For now we don’t have native mobile apps. Mobile users have to use DApp browser apps and navigate to the same site as desktop users. The layout of the fronted works well on different screen sizes as relatively narrow boxes are arranged per page. Depending on the width of the browser window, they will either be rendered next to each other or below one another.
Digital Wallet¶
The only, yet significant, difference a visitor of a Web DApp experiences compared to a Web App, is the need for a “bridge to the blockchain”. Also called a digital wallet. Its first task is to establish the connection to the blockchain network - either via a full node that users run themselves or via a gateway service like Infura. Its second task is to pop up whenever the user seeks to write data to the blockchain and enable the convenient signing of such transactions with the users private key.
There are many organizations and projects out there offering digital wallets in different stages of maturity and compatibility. While the trend goes towards deeper and native integration into browser (or even operation systems), for now the market appears scattered.
The digital wallet we are using ourselves, and that seems to be the currently best supported one out there, is MetaMask: metamask.io. MetaMask is available both as extension for desktop browsers (Chrome, Firefox, Opera and Brave) and as early-stage mobile app (iOS and Android).
Once you have a digital wallet, either restore an existing account or follow the process to create a new account. In most digital wallets, creating a new account involves the randomized mathematical creation of a new and unique mnemonic (also called “seed phrase”). From this, one or more accounts, each with a public address and a matching private key, can be derived deterministically. Meaning you only have to remember/store (the digital wallet will probably remind you thoroughly to do so) the mnemonic to restore your account(s) anytime on any machine. Usually only the first account per mnemonic will be used.
After having created your new account, don’t forget to switch to the Rinkeby Test Network. By default you will be on the Main Ethereum Network.
Getting Ether¶
After installing a digital wallet and creating an account, the last step before being ready to use FIN4Xplorer is to get some Rinkeby Ether (ETH). All transactions on the Ethereum (test) network cost Ether, the so called gas fee. The price depends on the current workload of the network as well as how many additions/changes to data on smart contracts your transaction causes. On test networks, Ether can be obtained for free from “faucets”. On the main network, Ether has either to be earned by being an active participant in the network (running a full node and doing mining), has to be traded or has to be bought on exchanges.
For obtaining Ether on the Rinkeby test network we suggest two options:
- Using the “authenticated faucet” at faucet.rinkeby.io requires a social media post
- We build our own little faucet server that gives a small amount of ETH per click if the user has less then a threshold value: click Request Ether on the landing page of demo.finfour.net and wait a little until you get a confirmation message.
Application overview¶
Home¶
Home acts as landing page and is the central place of the DApp.
The two main subsites are accessible in the bottom bar: Tokens and Claims.
The icons in the top bar are for showing pending transactions, the users QR code, reloading the page and for getting notified about new messages.
The various boxes shown are explained in the chapter More functionalities.
Tokens¶
Under Tokens new tokens can be created as described in Create tokens. On the right side all existing tokens are listed with direct links to claiming them or to view more details about them.
Clicking on View on a Token brings up a dedicated site showing details about the design and some performance statistics of the token.
Claims¶
The layout of the Claims site is analog to the Tokens site: submitting new claims can be done on the left side and a list of previous claims is displayed on the right side. If users get to this site via a Claim-Link on a token directly, the Token Type will be prefilled. More info about the claiming process can be found in Claim tokens.
Create tokens¶
The ability for anyone to create new tokens on the FIN4Xplorer plattform is at the heart of its concept. Once a token is created, it can be claimed by anyone. A successful claim results in having a balance on the respective token. Since we base our token contracts on the ERC-20 standard this balance will show up on any Ethereum digital wallet app that supports the ERC-20 standard. Note that also in such apps you have to switch to the Rinkeby testnet.
Token creation wizard¶
The effort put into creating a token can range from a quick 1-min-clicktrough to a lengthy eloborate planning in a multi-disciplinary team. The possible entry points for the token creation process are:
- Creating a new token from scratch
- Uploading a token draft in JSON format
- Copying an existing token design as template
The last two will import a token creation draft showing up at the bottom of the box. The first option will take you directly into the token creation wizard. It consists of 6 steps: Token identity, Token design, Action policy, Minting policy, Noninteractive verifiers and Interactive verifiers. In each step, an info box can be opened that provides explanations.
Note that at any point you can leave the wizard and your progess will be stored as draft. Drafts can be used to resume the process later on or to download, share and import them.
Once the 6 steps are completed, the token can be created on the blockchain. Two ore more transactions have to be confirmed for that. Two for the token-creation itself and one for each proof that has parameters. Until all proof-parameterization transactions are confirmed, the token will remain in a disabled state.
Claim tokens¶
Tokens that have been created as outlined in Create tokens, can be claimed.
Submitting a claim is the first step to obtaining a balance on the token in question. Once made, it shows up under My previous claims. Claims there can be in one of three stages:
- In red with a prompt to Submit proof, this is the default after submitting a new claim
- In green, the approved state, which also means that a balance has to be minted to the claimer
- In gray, the rejected state, if one or more of the proofs got manually or automatically rejected
A click on the filter-icon in the top right corner will open a menu that allows you to hide or show claims based on their three stages.
Proving¶
For a claim to be successful, all the verifiers specified by the token creator have to receive proof from the user and get approved - automatically or by the chosen person, group or sensor. A proof submission site might look like this.
Here, a verifier is shown (ClaimableOnlyNTimes) that didn’t have to be initated manually. It belongs to the category of verifiers that automatically give their approval or rejection once a claim is made.
Once all verifiers received proofs and are approved, the claim appears as green and the claimer gets a balance on this token.
If any verifier of a claim rejectes the provided proof, the entire claim gets rejected. It is not possible to recover this claim by resubmitting proofs - a new claim has to be made if the user wants to try again.
If verifiers depend on the approval of other users, they have a chance to add a message to the claimer together with their approval or rejection. This message is displayed on the respective proof submission site.
More functionalities¶
All the functionalities presented below are accessible via the Home site.
Wallet¶
The wallet box shows the users balance on all tokens with approved claims. The token name links to its respective detailed site (TODO ref).
The transfer icon links to a site allowing the transfer of balances on transferable tokens to other users.
Transfer Tokens¶
Note that once a transfer has been made, there is no way to undo it from the senders site. Only the recipient could choose to send it back.
Settings¶
Settings contains Links to the About and System settings sites. The latter contains the language preference and a list of relevant smart contract addresses.
Furthermore, User groups and Token collections can be found there.
User Groups¶
User groups can be used for two purposes. Firstly to define “administrators” of a token collection who can add or remove tokens from a collection. Secondly, certain proof types can notify members of a user group about a pending approval that one of them should approve or reject.
Under My groups users can message the owner (unless they are the owner) and leave groups (also possible for owners). Upon leaving a group, users can choose to notify the group owner about it or not.
Editing a group as owner comprises the options to add or remove members and to transfer ownership of the group.
Token collections¶
Token collections are a way to curate a list of tokens with a much lower effort then the community-curated approach of the token curated registry.
They can be used for organisations to promote their tokens in one place, for individuals to create portfolios or other use cases.
The collection creator can add or remove tokens from the collection, appoint an admin group to do the same or transfer ownership of the collection.
Inbox¶
Your messages shows all messages sent to you. These can be
- Proof contracts notifying you about pending approvals: for you directly or a group you are a member of
- System notifications like a user leaving a group you created
- Messages from other users
If you get a new message while being on the DApp, the notification bell in the top right corner of the site will turn yellow and take you to the messages site upon clicking.
Message user takes you to the option to message other users directly. The QR icon can be used to scan the public address of the recipient instead of having to type or paste it in.
Token curation¶
The token curation feature (Token Curated Registry, TCR) is currently disabled. If you are interested how it would look like, see the previous version of this documentation.
Sources of value¶
In an upcoming version we will activate a new feature we are working on. It will allow token creators to attach underlying sources of value to their token. This could be Bitcoin-bac ked ERC20 tokens, other tokens with special properties or just free text for something the token creator promises off-chain to redeem a token for.
The FIN4Documentation repository that this documentation is being build from is licensed under “Creative Commons Attribution Share Alike 4.0 International” (CC-BY-SA-4.0). Both the FIN4Xplorer repository as well as the FIN4Contracts repository are licensed under “GNU Affero General Public License v3.0” (AGPL-3.0).