> For the complete documentation index, see [llms.txt](https://muellners-1.gitbook.io/finscale/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://muellners-1.gitbook.io/finscale/functional-microservices/accounting.md).

# Accounting

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.

{% hint style="info" %}
See [this documentation](https://docs.docker.com/engine/install/ubuntu/) on how to install docker on ubuntu. Similar installation instructions exist for other distributions.
{% endhint %}

{% hint style="info" %}
Instructions on how to install docker-compose can be found [here](https://docs.docker.com/compose/install/).
{% endhint %}

#### 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](https://www.trufflesuite.com/ganache) 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

![](/files/-MT9CrU-ynOVf81wIHyB)

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](https://snapcraft.io/postman) store link using the command

```
snap install postman
```

### Running required services

The following services must be run beforehand:

1. [Finscale-Identity](https://github.com/muellners/finscale-identity): Provides the authentication mechanism.
2. [Finscale-Contracts](https://github.com/muellners/finscale-contracts): Creates a wallet with some Eth balance for the account initiating the transaction.

{% hint style="info" %}
In order to successfully run the [finscale-contracts](https://github.com/muellners/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](http://127.0.0.1:7545/)\
WEB3J\_WALLET\_PASSWORD=changeit\
WEB3J\_WALLET\_PATH=/home/${ USER }/.finscale/wallet.json 
{% endhint %}

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

![](/files/-MT9Z2Xz1QISti0nS8aK)

{% hint style="success" %}
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
{% endhint %}

### Running the accounting service

First, you need to set the following environment variables required by [finscale-accounting](https://github.com/muellners/finscale-accounting):

{% hint style="info" %}
WALLET\_PASSWORD=changeit\
WALLET\_PATH=/home/${ USER }/.finscale/wallet.json
{% endhint %}

Next, start the [JHipster Registry](https://www.jhipster.tech/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

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="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
}
```

{% endtab %}
{% endtabs %}

## Get Ledger

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="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": ""
}
```

{% endtab %}

{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

## Get All Ledgers

<mark style="color:blue;">`GET`</mark> `http://{{accountingUrl}}/ledgers`

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| Authentication | string | Authentication token |

{% tabs %}
{% tab title="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": ""
    }
]
```

{% endtab %}
{% endtabs %}