Accounting

This page explains the accounting micro-services.

Our goal is to enable IFRS standards of accounting that track a granular level of accounting.

Two types of accounting are part of Finscale's Accounting service: Cash-based and Accrual.

This service makes use of smart contracts to store information.

Setting Up

Prerequisites

Before attempting to run the project, you need the following installed on your system

1. Docker and Docker-Compose

2. Ganache GUI

3. Postman

Step1 - Install docker and docker-compose

Refer to the Docker docs for installation instructions.

See this documentation on how to install docker on ubuntu. Similar installation instructions exist for other distributions.

Instructions on how to install docker-compose can be found here.

Step 2 - Install Ganache GUI

Ganache is a tool used for setting up a personal Ethereum Blockchain for testing Solidity smart contracts.

First, navigate to the Truffle Suite official website and download the latest Linux release which will be the *.AppImage

Next, make the downloaded file executable

chmod a+x ganache-2.5.4-x86_64.AppImage

Next, run the file

./ganache-2.5.4-x86_64.AppImage

Upon successful installation, you should see a screen that looks like this

Click on the "QUICKSTART" button to get started.

Step 3 - Install Postman

This is required for testing the endpoints. You can install Postman on Linux by downloading it, or via the Snap store link using the command

snap install postman

Running required services

The following services must be run beforehand:

1. Finscale-Identity: Provides the authentication mechanism.
2. Finscale-Contracts: Creates a wallet with some Eth balance for the account initiating the transaction.

In order to successfully run the finscale-contracts project, you need to set some environment variables the program requires which are provided below:

WEB3J_NODE_URL=http://127.0.0.1:7545 WEB3J_WALLET_PASSWORD=changeit WEB3J_WALLET_PATH=/home/${ USER }/.finscale/wallet.json

Assuming you have already created the directory using

mkdir ~/.finscale

And ${ USER } is the current user of your system

If you're using IntelliJ IDE, the above env variables can be easily set by going to

Run > Edit Configurations... > Environment variables

WEB3J_NODE_URL points to Ganache's RPC server default address

If the project has run successfully, you should now see a wallet.json file created in the directory with some content e.g, /home/cadreia/.finscale/wallet.json

Running the accounting service

First, you need to set the following environment variables required by finscale-accounting:

WALLET_PASSWORD=changeit WALLET_PATH=/home/${ USER }/.finscale/wallet.json

Next, start the JHipster Registry by running the following command at the root of the project

docker-compose -f src/main/docker/jhipster-registry.yml up

Then, run the project and you should now have access to the API.

Testing the endpoints

Create Ledger

POST http://{{accountingUrl}}/ledgers

Creates a new ledger

Headers

Name	Type	Description
Authentication	string	Authentication token

Request Body

Name	Type	Description
showAccountsInChart	boolean
type	string
description	string
name	string
identifier	string	uniquely identifies a ledger

200 Ledger successfully created

{
  "id": "eea5ee01-9cbf-48b0-8e12-48bea35c75e0",
  "identifier": "new",
  "name": "New Ledger",
  "type": "LIABILITY",
  "description": "New Ledger description",
  "totalValue": null,
  "showAccountsInChart": true,
  "parentLedgerId": null
}

Get Ledger

GET http://{{accountingUrl}}/ledgers/:id

Path Parameters

Name	Type	Description
id	string	ID of the ledger to get

Headers

Name	Type	Description
Authentication	string	Authentication token

200 Ledger successfully retrieved

{
  "id": "eea5ee01-9cbf-48b0-8e12-48bea35c75e0",
  "identifier": "new",
  "name": "New Ledger",
  "type": null,
  "description": "New Ledger description",
  "totalValue": 0,
  "showAccountsInChart": true,
  "parentLedgerId": ""
}

404 Could not find a ledger matching this query

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Not Found",
  "status": 404,
  "detail": "404 NOT_FOUND",
  "path": "/api/ledgers/eea5ee01-9cbf-48b0-8e12-48bea35c75e",
  "message": "error.http.404"
}

Get All Ledgers

GET http://{{accountingUrl}}/ledgers

Headers

Name	Type	Description
Authentication	string	Authentication token

200 Ledgers successfully retrieved

[
    {
        "id": "eea5ee01-9cbf-48b0-8e12-48bea35c75e0",
        "identifier": "new",
        "name": "New Ledger",
        "type": null,
        "description": "New Ledger description",
        "totalValue": 0,
        "showAccountsInChart": true,
        "parentLedgerId": ""
    }
]