Aion4j Faucet Support Flow

Aion4j Maven Plugin's Faucet support uses two main components

• Aion Faucet Smart Contract (Deployed on Mastery testnet network)
• Aion Faucet Service (Web app)

Aion Faucet Service

This is a centralized hosted web app. It helps to transfer some initial Aion tokens to a new account. The actual transaction happens in the Faucet Smart contract. But this service sends the transaction using a pre-defined operator account. Source Code

Aion Faucet Smart Contract

A Java Smart Contract deployed on Mastery testnet network. Source Code.

This smart contract controls who can request for top-up, top-up amount and request frequency.

Top-up Flow for a new account

Using just one command aion4j:account -Dcreate -Dtopup, you can create and allocate some testnet tokens for your test account.

The following is a sample flow for account top-up using maven. When developer runs mvn aion4j:account -Dcreate -Dtopup,

1. Maven plugin creates a new account and shows both address and private key.
2. Maven plugin checks the account balance in testnet network.
3. If, account balance is zero, Maven plugin tries to allocate some initial balance to the newly created account. The following steps are done if it's an account with zero balance:

   • Maven plugin makes a call to http://<faucet-web-service-url/challenge to get a challenge. The Faucet service creates a challenge in server side and sends it back to maven client. The challenge has mainly three components - challenge no, difficulty, a random string. The faucet service keeps the challenge in server side for sometime (~ 2min), so that it can be used for verification later.

   • After getting the challenge from faucet-service, Maven plugin now tries to generate a HashCash value with the difficulty level in the challenge. Maven plugin finds the solution for the challenge with data (challenge no and random string)

   • Maven plugin sends the HashCash solution to the faucet service.

   • Faucet service gets the challenge no from the HashCash solution and finds the challenge definition stored in the server side.

   • Faucet service then verifies the difficulty level and message in the solution with the server side value.

   • If verification is ok, Faucet service sends a transaction for registerAddress method on Faucet Smart contract. Faucet service uses an operator account (which is already registered in Smart Contract) to send this transaction.

     • Aion Faucet Smart Contract gets the registerAddress request for a new account. It registers the account with Smart Contract and allocates a minimum balance (~0.5 Aion).
     • Now the newly created account has some balance to request for top-up without centralized Faucet service.

   • If hashcash solution verification failed, Faucet service throws exception and top-up fails.

   • To reduce or avoid any abuse to the system, the Faucet service keeps track of no of new accounts top-up done from a client IP within a specific duration. If it crosses the threshold (now 3 accounts within 1hr), the difficulty level automatically increases for additional requests and the client gets a higher difficulty level to solve the challenge.

   • Once the initial top-up is done for an account, the centralized Faucet service is no longer required for that account.

   • Maven plugin now sends topup method call transaction to the smart contract. But using newly created client address and private key.

   • The Faucet smart contract checks if the registerAddress method has already been called for the account. It checks the registered address map to find that.

   • If registerAddress is already done, the smart contract now transfers some per-defined amount of Aion coins to the address.

   • The smart contract also checks if the number of top-up requests for an account is below the daily limit. (Currently 3 times per 24hrs)

The Faucet smart contract has following roles:

• Owner account: Needed for deployment, add operator account, get refund balance during contract destruction.
• Operator account: Multiple operator accounts. Operator account is used to do the registration of a new address and initial top-up;
• Account : User's account asking for top-up.