NexaLedger

NexaLedger is an end-to-end Web3 platform demo for tokenization, on-chain payments, and account-abstraction wallet controls.

What it demonstrates

• Tokenized receivables via InvoiceNFT
• Stablecoin settlement rails via PaymentEscrow
• Delegated wallet policy controls via SmartAccount + PermissionManager
• Backend relayer/indexer APIs using Express + ethers
• Premium dashboard UI in Next.js

Why this matches the target role

• Tokenization and payments:
  • Invoice minting + escrow-based settlement flows map directly to digital asset use cases.
• Account abstraction and wallet architecture:
  • Session-key controls and per-function spend limits demonstrate delegated wallet design.
• End-to-end Web3 delivery:
  • Smart contracts, backend APIs, and polished frontend are integrated in one platform.
• Security and quality:
  • Foundry tests, static analysis notes, and threat model documentation are included.
• Product and architecture collaboration readiness:
  • Clear architecture docs and implementation tradeoffs are captured for team decision-making.

Screenshots

• Dashboard overview: docs/screenshots/dashboard-desktop.png
• Ledger and policy controls: docs/screenshots/dashboard-mobile.png

Repository layout

• contracts/: Solidity contracts, tests, and Foundry config
• backend/: REST APIs, chain client, deployment script
• frontend/: dashboard and UX flows
• docs/: architecture, threat model, and security scan notes

Prerequisites

• Node.js 20+
• pnpm
• Foundry (forge, anvil, cast)

Quick start

1. Install workspace dependencies

cd "/Users/abdelrahaman/Desktop/BLOCKCHAIN PROJECT/NexaLedger"
pnpm install

2. Install Foundry test library

cd contracts
forge install foundry-rs/forge-std

3. Start local chain

anvil --host 127.0.0.1 --port 8545

4. Run contract tests

cd "/Users/abdelrahaman/Desktop/BLOCKCHAIN PROJECT/NexaLedger/contracts"
forge test --offline -vv

5. Deploy contracts and generate env files

cd "/Users/abdelrahaman/Desktop/BLOCKCHAIN PROJECT/NexaLedger"
pnpm deploy:local

This writes:

• backend/.env
• frontend/.env.local
• docs/local-deployment.json

6. Build + run services

cd "/Users/abdelrahaman/Desktop/BLOCKCHAIN PROJECT/NexaLedger"
pnpm --filter nexaledger-backend build
pnpm --filter nexaledger-frontend build

# terminal 1
cd backend && node dist/index.js

# terminal 2
cd frontend && pnpm start --hostname 127.0.0.1 --port 3000

• Backend: http://localhost:4000/api/health
• Frontend: http://127.0.0.1:3000

Core contract behavior

• InvoiceNFT.sol

  • Mints invoice NFTs with payer/token/amount/due-date metadata
  • Tracks lifecycle state: Created -> Funded -> Released/Refunded

• PaymentEscrow.sol

  • Locks settlement tokens from payer
  • Requires bilateral approvals for release or refund
  • Supports emergency refund after due-date grace period

• PermissionManager.sol

  • Defines per-account actor permissions by target + selector + token
  • Enforces daily spend ceilings

• SmartAccount.sol

  • Owner and session-key execution model
  • Enforces policy checks before delegated execution

Security review

cd contracts
/Users/abdelrahaman/Library/Python/3.9/bin/slither . --exclude-dependencies

• Findings summary and dispositions: docs/security-scan.md

API surface

• POST /api/invoices
• POST /api/invoices/:id/fund
• POST /api/invoices/:id/release
• POST /api/invoices/:id/refund
• POST /api/wallet/session-keys
• POST /api/wallet/permissions
• POST /api/wallet/execute

CI and deployment automation

• CI workflow: .github/workflows/ci.yml
• Sepolia deploy workflow: .github/workflows/deploy-sepolia.yml

To use the deploy workflow, set repository secrets:

• SEPOLIA_RPC_URL
• PRIVATE_KEY
• ISSUER_ADDRESS
• PAYER_ADDRESS

Demo flow

1. Create invoice in UI
2. Fund invoice escrow
3. Release settlement
4. Configure session key and permission policy
5. Execute wallet action via controlled account abstraction path