README.md

Getting Started

The Transaction Tool backend is responsible for facilitating the process by which a transaction is required to be signed by multiple users. This includes creating, sharing, collecting signatures, preparing for submission, and executing the transactions to the specified network.

Usage Modes

Personal User Mode: You do not need to set up your local backend to use the application in personal mode. Personal mode allows you to create, sign and submit transactions that requires one user to sign.

Organizational User Mode: The Transaction Tool application can be used without setting up the backend in personal mode. The backend is not required if you are not developing features in the Organization flow. To setup the frontend application, Follow the complete setup process below..

Prerequisites

• Node.js

  • Required version: >= 24.19.0 <25

  • Verify installation:

    node -v

• pnpm

  • Required version: >= 9.13.1

  • Installation of pnpm(if not already installed):

    npm install -g pnpm@latest

  • Verify installation:

    pnpm --version

• Python setuptools

  • Required version: >= 75.6.0

  • Installation of python-setuptools with brew:

    brew install python-setuptools

  • Verify installation:

    python -m setuptools --version

• Redis 7.0+

  • Required for IP-based rate limiting on sensitive endpoints. The IpResetPasswordUniqueEmailGuard uses the EXPIRE ... NX command introduced in Redis 7.0. Earlier versions will silently skip the expiry, causing rate limit keys to persist indefinitely.

• Docker Desktop with Kubernetes enabled

  • Enable Kubernetes: Docker Desktop → Settings → Kubernetes → Enable Kubernetes → Apply & Restart.

1. Clone the project

git clone https://github.com/hashgraph/hedera-transaction-tool.git
cd hedera-transaction-tool

2. Install dependencies

The repository is a single pnpm workspace, so dependencies are installed from the root once for all modules (back-end, front-end, automation):

pnpm install

Back-end-specific scripts can then be run via the workspace filter (from any directory). pnpm matches against the name field in package.json; the back-end's NestJS apps are scoped (@back-end/api, @back-end/chain, @back-end/notifications), and -F matches the un-scoped tail:

pnpm -F back-end <script>          # e.g. pnpm -F back-end build:all
pnpm -F api test:cov               # resolves to @back-end/api
pnpm -F chain test:cov             # resolves to @back-end/chain
pnpm -F notifications test:cov     # resolves to @back-end/notifications

Or by cd back-end and running the script as before — both work.

3. Environment Configuration

Create .env files from the provided example.env templates in each of the following directories:

• apps/api
• apps/chain
• apps/notifications
• typeorm
• scripts
• the root one

The default values work for development.

4. Email API Configuration

An email api account enables you to set-up the notification system in the application. You will need to create a free tier Brevo account, or another provider of your choosing.

Note: some providers require no username and password, such as Gmail's smtp-relay service. These values, therefore, are optional.

Example: Create Brevo Account:

1. Create a free tier Brevo account
2. Log in to your account.
3. Select the drop down menu in the top-right corner (next to the notifications icon).
4. Select Settings from the dropdown menu.
5. In the left sidebar under Organization settings, select SMTP & API.
6. Locate your SMTP key in the SMTP keys table.
7. (Optional) If no SMTP key appears, select Generate a new SMTP Key in the top-right corner.
8. Copy the SMTP key value and add it to your apps/notifications/.env:

   EMAIL_API_HOST=smtp-relay.brevo.com
   EMAIL_API_PORT=587
   EMAIL_API_SECURE=false
   EMAIL_API_USERNAME=<your Brevo login email>
   EMAIL_API_PASSWORD=<your SMTP key from step 6>
   SENDER_EMAIL=no-reply@<yourdomain.com>

Local Docker Compose Development

Use the base compose file for CI-style container runs, and add the dev overlay when you want source bind mounts and a persisted local Postgres data directory. Run from the back-end/ directory — the compose files use context: .. so the build context resolves to the repository root:

docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up --build

5. Create Email API Secret for Kubernetes

(First time only) Create email-api-secret.yaml from the example template:

1. Navigate to backend/k8s/dev/
2. Copy email-api-secret.example.yaml to email-api-secret.yaml
3. Update the file with your Brevo (or other provider) credentials from step 4.

6. Deployment on Kubernetes

Ensure Kubernetes cluster is running (Docker Desktop with Kubernetes enabled).

HTTPS Mode Setup (Preferred)

(First time only) Create self-signed certificates for HTTPS. Required for testing with the built Electron client application.

1. Install mkcert (macOS example):

   brew install mkcert

2. Create cert directory (if it doesn't exist):

   mkdir -p cert

3. Generate certificates:

   mkcert -install
   mkcert -key-file ./cert/key.pem -cert-file ./cert/cert.pem localhost

Deployment Options

You can deploy using either the automated script (preferred) or manual steps.

Option 1: Automated Deployment (Preferred)

pnpm deploy:dev
# or
./deploy.sh

Option 2: Manual Deployment

1. (First time only) Create Kubernetes secret for self-signed certificate:

   kubectl create secret tls self-signed-certificate --cert=./cert/cert.pem --key=./cert/key.pem

2. (On backend changes only) Build Docker images from the repository root (the build context is the root, so the workspace lockfile and shared package manifests are visible):

   # API service
   docker build -t back-end-api:1.0.0 -f back-end/apps/api/Dockerfile .
   
   # Chain service
   docker build -t back-end-chain:1.0.0 -f back-end/apps/chain/Dockerfile .
   
   # Notifications service
   docker build -t back-end-notifications:1.0.0 -f back-end/apps/notifications/Dockerfile .

3. Apply deployments (from back-end/):

   kubectl apply -f ./k8s/dev/deployments

4. Install Ingress Controller:

   helm repo add traefik https://helm.traefik.io/traefik
   helm repo update
   helm install traefik traefik/traefik

5. Apply Ingress configuration:

   kubectl apply -f ./k8s/dev/ingress.yaml

6. Expose PostgreSQL service:

   kubectl port-forward svc/postgres 5432:5432

Exposed Endpoints:

All ports are defined in the docker-compose.yaml file. The default ports are:

Type	Endpoint
API Service Endpoint	https://localhost
Notifications Service Endpoint	https://localhost/notifications
PgAdmin	https://localhost:5050

Stopping the Deployment

To stop all services:

kubectl delete --all deployments,ingresses
helm uninstall traefik

Adding a Local Organization to Your Local Development Environment

To add the local organization to your application for development:

Create your admin

Ensure your local database is running, then create an admin user:

cd backend/scripts
pnpm create-admin

Follow the prompts to:

• Enter an email address (can be any email).
• Enter a password (can be any password).

Add an Organization

1. Go to the Transaction Tool application.
2. Select Add an organization.
3. Enter a name for your local organization.
4. Enter the local server URL: https://localhost

Testing

Tests are run separately for each service. Navigate to the service you want to test and run the test commands:

API

cd apps/api
pnpm test:cov

Notifications

cd apps/notifications
pnpm test:cov

Chain

cd apps/chain
pnpm test:cov

Troubleshooting

1. If you encounter setup problems:

   • Delete the node_modules folder in the frontend or backend or both directories. Reinstall node_modules with pnpm install.
   • Delete the pgdata folder found in the backend directory. Run docker compose --build.
   • Verify you are connected to your local development backend to observe the deployed changes and not your staging backend.

2. When installing traefik, if you receive Error: INSTALLATION FAILED: cannot re-use a name that is still in use:

   helm upgrade traefik traefik/traefik

3. Docker Image Pull Errors

If you encounter Cloudflare storage connection errors:

error pulling image configuration: download failed after attempts=6:
dialing docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com:443

Solution: Use DockerHub Mirror

1. Pull from mirror registry:

   docker pull mirror.gcr.io/library/node:24.19.0-alpine

2. Tag the image:

   docker tag mirror.gcr.io/library/node:24.19.0-alpine node:24.19.0-alpine

Alternative: Configure Docker Desktop Registry Mirrors:

1. Open Docker Desktop → Settings → Docker Engine.
2. Add registry mirror configuration:

   {
     "registry-mirrors": [
       "https://your-mirror-url/"
     ]
   }
   

3. Click Apply & Restart.