FlowLedger 🚀

A lightweight dApp to track daily expenses and income, securely storing transaction summaries on-chain via Stacks. Built with two custom npm packages purpose-built for the Stacks ecosystem.

Features ✨

🔗 Leather Wallet Integration — Connect your Stacks wallet and submit transactions on-chain
📊 Spending Analytics — Doughnut chart showing income vs expenses breakdown
⚡ Quick Log — One-click buttons for common transactions (Coffee, Lunch, Salary, etc.)
🔍 On-Chain Lookup — Read any transaction stored in the smart contract
📜 Live Contract — Powered by a Clarity smart contract deployed on Stacks mainnet
📦 Custom NPM Packages — Two ecosystem packages published on npm for Stacks developers

NPM Packages 📦

FlowLedger is powered by two published npm packages built specifically for the Stacks blockchain ecosystem. Both packages are published on the public npm registry under the gojo89427 npm account.

📦 flowledger-dapp

The complete FlowLedger DApp package — a daily transaction tracker for Stacks.


npm	`@sawera-mastoi/flowledger-dapp`
Version	`1.0.3`
License	MIT
Author	FlowLedger Team
Registry	npmjs.com/package/flowledger-dapp

Install

npm install @sawera-mastoi/flowledger-dapp

What's Included

The flowledger-dapp package contains the full FlowLedger application:

Frontend — HTML/CSS/JS interface for tracking daily expenses & income
Clarity Smart Contracts — On-chain transaction storage (transactions.clar, simple-counter.clar, simple-token.clar, simple-profile.clar)
FlowLedger SDK (@earnwithalee/flowledger-sdk) — Official SDK for interacting with FlowLedger smart contracts
stacks-echo-kit dependency — Utility toolkit for STX formatting, address validation, and API helpers

Dependencies

{
  "dependencies": {
    "@earnwithalee/flowledger-sdk": "file:./packages/flowledger-sdk",
    "stacks-echo-kit": "^1.0.0"
  }
}

Usage

// Import the full DApp project
const flowledger = require('flowledger-dapp');

// The package integrates directly with the Stacks blockchain
// It bundles the FlowLedger SDK and stacks-echo-kit

📦 stacks-echo-kit

A lightweight utility toolkit for the Stacks blockchain ecosystem. Includes STX formatting, address validation, transaction helpers, price utilities, and network configuration tools.


npm	`stacks-echo-kit`
Version	`1.0.0`
License	MIT
Author	earnwithalee
Registry	npmjs.com/package/stacks-echo-kit
Repository	github.com/sawera-mastoi/stacks-tue

Install

npm install stacks-echo-kit

API Reference

STX Conversion

const kit = require('stacks-echo-kit');

// Convert STX to microSTX
kit.stxToMicro(2.5);        // → 2500000

// Convert microSTX to STX
kit.microToStx(2500000);    // → 2.5

Address Utilities

// Validate a Stacks address
kit.isValidAddress("SP3AMZ74TRAWC92ZB110E38SZB7F1T06EHZ38QMH4");
// → true

kit.isValidAddress("invalid-address");
// → false

// Truncate address for UI display
kit.truncateAddress("SP3AMZ74TRAWC92ZB110E38SZB7F1T06EHZ38QMH4", 6, 4);
// → "SP3AMZ...QMH4"

STX Formatting

// Format STX for display
kit.formatStx(2.5);         // → "2.50 STX"
kit.formatStx(1000000);     // → "1,000,000.00 STX"

// Compact formatting for large values
kit.formatCompact(1500000); // → "1.5M STX"

API URL Builder

// Build Hiro API URLs for mainnet
kit.buildApiUrl("/extended/v1/tx", "mainnet");
// → "https://stacks-node-api.mainnet.stacks.co/extended/v1/tx"

// Build Hiro API URLs for testnet
kit.buildApiUrl("/v2/accounts/SP123.../balances", "testnet");
// → "https://stacks-node-api.testnet.stacks.co/v2/accounts/SP123.../balances"

Explorer URLs

// Get Stacks Explorer transaction URL
kit.getExplorerTxUrl("0xabc123...", "mainnet");
// → "https://explorer.stacks.co/txid/0xabc123...?chain=mainnet"

Full List of Exported Functions

Function	Description
`stxToMicro(amount)`	Convert STX to microSTX
`microToStx(amount)`	Convert microSTX to STX
`isValidAddress(address)`	Validate a Stacks address format
`truncateAddress(address, start, end)`	Shorten address for display
`formatStx(amount)`	Format STX with 2 decimal places
`formatCompact(amount)`	Compact number format (K, M, B)
`buildApiUrl(path, network)`	Build Hiro node API URLs
`getExplorerTxUrl(txId, network)`	Get Stacks Explorer URL for a tx

Keywords

stacks · stx · blockchain · bitcoin · clarity · web3 · defi · wallet · hiro · leather · xverse · talent-protocol · builder-rewards · ecosystem

Installation

Install the full project 🚀

# Clone the repo
git clone https://github.com/sawera-mastoi/FlowLedger.git
cd FlowLedger

# Install dependencies (including stacks-echo-kit from npm)
npm install

Install packages individually

# Install the full DApp package
npm install @sawera-mastoi/flowledger-dapp

# Install the Stacks utility toolkit
npm install stacks-echo-kit

Quick Start

1. Using FlowLedger SDK with stacks-echo-kit

const { FlowLedgerSDK } = require('@earnwithalee/flowledger-sdk');
const kit = require('stacks-echo-kit');

// Initialize the SDK
const sdk = new FlowLedgerSDK({
  contractAddress: 'SP3AMZ74TRAWC92ZB110E38SZB7F1T06EHZ38QMH4',
  contractName: 'transactions-v2',
  network: 'mainnet'
});

// Connect wallet
const address = await sdk.connect();
console.log('Connected:', sdk.formatAddress(address));

// Add a transaction
await sdk.addTransaction({
  amountSTX: 5.0,
  memo: 'Coffee purchase',
  type: 'expense'
});

// Get balance using stacks-echo-kit under the hood
const balance = await sdk.getBalance(address);
console.log('Balance:', sdk.formatSTX(balance));

// Validate addresses
console.log(sdk.isValidAddress(address)); // true

2. Using stacks-echo-kit standalone

const kit = require('stacks-echo-kit');

// Quick STX calculations
const microAmount = kit.stxToMicro(10);      // 10000000
const stxAmount = kit.microToStx(5000000);   // 5.0

// Build API requests
const url = kit.buildApiUrl('/extended/v1/tx/0xabc123', 'mainnet');
const response = await fetch(url);
const txData = await response.json();

// Format for UI
console.log(kit.formatStx(stxAmount));       // "5.00 STX"
console.log(kit.truncateAddress(address));   // "SP3AMZ...QMH4"

3. Run the DApp locally

# Install dependencies
npm install

# Serve locally
npx serve .

# Open http://localhost:3000 in your browser
# Install Leather Wallet extension and connect

Project Structure 📂

FlowLedger/
│
├── package.json                # Monorepo manager (npm workspaces)
├── README.md                   # This file
├── serve.ps1                   # Local development server script
│
├── packages/
│   ├── flowledger-dapp/        # Main App (npm: flowledger-dapp)
│   │   ├── index.html          # Main application UI
│   │   ├── app.js              # Frontend logic
│   │   ├── style.css           # Styling
│   │   ├── contracts/          # Clarity Smart Contracts
│   │   ├── public/             # Static assets (logo, sdk-bundle)
│   │   └── package.json        
│   │
│   ├── stacks-echo-kit/        # Utility Kit (npm: stacks-echo-kit)
│   │   ├── index.js            # Toolkit logic
│   │   ├── README.md           # Documentation
│   │   └── package.json        
│   │
│   └── flowledger-sdk/         # Official SDK (npm: @earnwithalee/flowledger-sdk)
│       ├── index.js            
│       ├── utils.js            
│       └── package.json        
│
├── .github/                    # GitHub workflows
└── vercel.json                 # Vercel deployment config

Smart Contracts 📜

Our contracts are written in Clarity and deployed on Stacks.

FlowLedger deploys several Clarity smart contracts on the Stacks blockchain:

Contract	Description
`transactions.clar`	Core contract — stores daily income/expense entries on-chain
`simple-counter.clar`	A basic counter contract for tracking transaction counts
`simple-token.clar`	Token contract for FlowLedger ecosystem
`simple-profile.clar`	User profile storage on Stacks

All contracts are written in Clarity, the decidable smart contract language for the Stacks blockchain (Bitcoin Layer 2).

Stacks May Event Requirements

To participate in the Stacks May event on Talent Protocol, ensure you meet the following:

Wallet Connection: Connect a Bitcoin L2 (Stacks-compatible) wallet to talent.app.
On-Chain Activity: Rewards are often based on verified on-chain contributions (smart contract deployments, transaction volume, etc.).
Open-Source Contribution: Maintain active GitHub contributions to your project repository.
NPM Packages: Publish and maintain ecosystem packages on the npm registry.
Compliance: Ensure your wallet address is compliant with international regulations (non-OFAC SDN).
Submission: Monitor the Talent Protocol dashboard for specific "Builder Challenge" submission buttons or leaderboard entry requirements.

Roadmap 🗺️

Future features and improvements planned for FlowLedger.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

For security-related issues, please see SECURITY.md.

License

This project is licensed under the MIT License — see LICENSE for details.

Built for the Stacks May Project on Talent Protocol. 🚀

Published NPM Packages:

📦 flowledger-dapp — Full DApp package
📦 stacks-echo-kit — Stacks utility toolkit

Name		Name	Last commit message	Last commit date
Latest commit History 1,727 Commits
.github		.github
demo-install		demo-install
demo-site		demo-site
flowledger-sdk-repo		flowledger-sdk-repo
packages		packages
scratch		scratch
temp_boost/r_48		temp_boost/r_48
test-install		test-install
test-my-pkg		test-my-pkg
test_pkg_install		test_pkg_install
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
boost_1000.js		boost_1000.js
boost_100_quality_commits.js		boost_100_quality_commits.js
boost_500.js		boost_500.js
boost_downloads.ps1		boost_downloads.ps1
boost_final.js		boost_final.js
boost_js.js		boost_js.js
boost_mega.js		boost_mega.js
eslint.config.js		eslint.config.js
feature_evolution.js		feature_evolution.js
friend_workflow_template.yml		friend_workflow_template.yml
make_commits.js		make_commits.js
make_commits_pro.js		make_commits_pro.js
package-lock.json		package-lock.json
package.json		package.json
serve.ps1		serve.ps1
validator.py		validator.py
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

FlowLedger 🚀

Table of Contents

Features ✨

NPM Packages 📦

📦 flowledger-dapp

Install

What's Included

Dependencies

Usage

📦 stacks-echo-kit

Install

API Reference

STX Conversion

Address Utilities

STX Formatting

API URL Builder

Explorer URLs

Full List of Exported Functions

Keywords

Installation

Install the full project 🚀

Install packages individually

Quick Start

1. Using FlowLedger SDK with stacks-echo-kit

2. Using stacks-echo-kit standalone

3. Run the DApp locally

Project Structure 📂

Smart Contracts 📜

Stacks May Event Requirements

Roadmap 🗺️

Contributing

Security

License

Stacks May Update

Evolution Complete

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages