CalorieApp 🍎

A mobile-first cryptocurrency wallet and food tracking application for CalorieToken on the XRP Ledger, built with KivyMD.

Latest Update (2025-11-18 – v1.1.1): Repository hardening, public-safe documentation index, UX layout consistency, security enhancements. See CHANGELOG. Pending merge from branch chore/repo-hardening.

⚖️ Legal & Beta Testnet Disclaimer

This software ("CalorieApp") is a pre‑release beta operating solely on the XRP Ledger Testnet. By accessing, cloning, building, or using any portion of this repository you acknowledge and agree to the following clauses:

Experimental Status: All features (wallets, tokens, NFT, DEX, food tracking, UI components) are experimental and subject to modification, suspension, or removal without notice prior to any mainnet launch.
No Real Value: Testnet XRP and any Testnet units or representations of CalorieToken ($CAL) have no monetary, redeemable, or transferable real‑world value.
No Advice: Nothing in the code, documentation, interfaces, commit history, issues, or generated outputs constitutes financial, investment, legal, medical, nutritional, or tax advice. Do your own due diligence.
No Solicitation: This repository does not solicit investment, purchase of tokens, securities, or any regulated financial instruments.
Risk Acceptance: You accept all risks associated with running beta code including potential data loss, malfunction, incorrect balances, performance issues, or security defects.
No Warranty: Provided "AS IS" without warranties of any kind (express or implied), including but not limited to merchantability, fitness for a particular purpose, non‑infringement, accuracy, reliability, or availability.
Limitation of Liability: CalorieToken, contributors, maintainers, and affiliates shall not be liable for any direct, indirect, incidental, consequential, special, exemplary, or punitive damages arising out of or in connection with use of or inability to use this beta software.
Intellectual Property: CalorieToken® trademarks, logos, and brand assets are protected. See docs/TRADEMARK.md for permitted usage. No license to brand assets is granted beyond the repository’s stated custom dual license.
Data Handling: The current beta architecture stores sensitive wallet materials locally (encrypted). You are responsible for safeguarding keys, mnemonics, passwords, and exported data. No cloud custody is provided.
Security Posture: While reasonable hardening steps are taken, the software has not undergone formal third‑party security audits. Treat all cryptographic operations as provisional.
Forward‑Looking Statements: Roadmap items, planned features, scaling targets, or performance goals are forward‑looking and inherently uncertain.
Jurisdiction: Usage is subject to applicable laws in your jurisdiction. If local regulations restrict interaction with beta blockchain software, you must discontinue use.
Contribution Disclosure: Pull requests, issues, or discussions may become publicly visible. Do not submit proprietary, confidential, or sensitive personal data.
Licensing: Code usage is governed by the Custom Dual License (personal/educational permitted; commercial/public distribution requires written permission). See LICENSE.
Monitoring: Public transparency of development is provided; you can review ongoing commits, branches, and releases at: https://github.com/CalorieToken/CalorieAppTestnet

If you disagree with any clause, do not use, clone, build, or distribute this software.

Contact (Licensing / Compliance / Security): info@calorietoken.net

🪙 CalorieToken Integration

Official CalorieToken XRPL Token:

Currency: Calorie
Ticker: $CAL
Issuer: rNqGa93B8ewQP9mUwpwqA19SApbf62U7PY
Network: XRP Ledger Mainnet (Testnet for development)
Website: calorietoken.net
Whitepaper: Read here

"Aiming to be the world's food token"
CalorieToken targets the worldwide food & beverage industry with blockchain-based payment solutions.

Learn More:

Official Documentation Index
Trademark Guidelines - Usage policies
CalorieToken Website - Official resources

🌟 High-Level Feature Matrix

Area	Implemented	Notes
Multi‑Wallet XRPL	✅	Create/import; encrypted storage
Mnemonic (BIP39)	✅	12‑word generation, verify, import
Token Support	✅	Generic framework + trustlines
Transactions	✅	XRP & tokens; visual history indicators
Offline Mode	✅	Deterministic tours/testing
Multi‑Server Failover	✅	Rotating endpoints, graceful degradation
NFT Screens	⏳	Mint flow refinement pending
DEX Trading	⏳	Offer & market UI polishing
Food Tracking	✅	Nutrition logging baseline
Responsive System	✅	Size classes, lazy recompute, overlay (withheld)
Social Assets	✅	Dynamic image generator (edge‑to‑edge typography)
Accessibility	🚧	Contrast audit scheduled
Performance Profiling	🚧	Planned instrumentation
CalorieDB Sync	🔜	Deferred (isolated)
WalletConnect	🔜	Phase 1 design queued
Web3 Browser	🔜	Deferred (flagged)

Legend: ✅ Complete · ⏳ Partial · 🚧 In Progress · 🔜 Planned

🛠️ Technical Stack

Frontend: KivyMD 2.0.dev (master)
Backend: Python 3.12
Blockchain: XRPL (XRP Ledger) Testnet
Mnemonic: BIP39 for 12-word recovery phrases
Networking: httpx with async support
Encryption: cryptography library
Data Storage: shelve (encrypted)

🏗️ Project Structure

CalorieAppTestnet/
├── README.md              # You are here
├── LICENSE                # Custom dual license
├── main.py                # Application entry point
├── requirements.txt       # Python dependencies
├── setup.py              # Package configuration
├── buildozer.spec        # Android build config
├──
├── .github/              # CI/CD workflows
├── assets/               # Images and resources
├── docs/                 # 📚 All documentation
│   ├── QUICK_START.md
│   ├── CONTRIBUTING.md
│   ├── CHANGELOG.md
│   ├── TODO.md
│   └── ... (guides & references)
├── scripts/              # 🔧 Build & utility scripts
│   ├── ux_tour.py
│   ├── build_apk.bat
│   └── run.py
├── src/                  # 💻 Source code
│   ├── VERSION.py
│   ├── core/
│   ├── screens/
│   └── utils/
└── tests/               # 🧪 Unit tests

Note: We follow industry best practices with a clean root directory. Additional internal references are intentionally withheld until stable release.

Layout Organization (Modernized)

The UI is organized into maintainable, screen-focused KV files with a clear loading order. This approach improves iteration speed and keeps layouts consistent without exposing internal file structure. The modernized setup enables:

Cleaner diffs and easier collaboration
Reduced duplication and warnings
Faster targeted layout updates

Conditional Navigation System

The app features an intelligent navigation system that creates navigation drawers only for screens that need them:

Screens WITH Navigation Drawers:

Wallet Screen
Settings Screen
Food Tracking Screen
DEX Trading Screen
NFT Minting Screen

Screens WITHOUT Navigation Drawers:

Login Screen
Transaction Screens (Send XRP, Send Tokens)
Setup/Import Screens
Intro/First Use Screens
Mnemonic Display/Verify Screens

XRPL Multi-Server Failover

Robust connectivity with automatic failover:

Primary: https://testnet.xrpl-labs.com
Backup: https://s.altnet.rippletest.net:51234
Backup: https://testnet.xrplapi.com
Backup: https://xrplcluster.com

XRPL Response Caching

Lightweight in-memory caching for select XRPL requests (e.g. ServerInfo) reduces redundant network calls and stabilizes performance under intermittent connectivity. Cache entries automatically expire after a short TTL.

🚀 Getting Started (Pre-Release Notice)

⏳ Deferred Components (Isolated)

The following planned features are isolated under feature flags and excluded from the active beta build:

Web3 Browser Screen (ENABLE_WEB3_BROWSER=False): Future in-app browsing / WalletConnect surface.
CalorieDB Sync Layer (ENABLE_CALORIE_DB=False): Planned decentralized product scan indexing (IPFS + BigchainDB).
XRPL ↔ CalorieDB Sync Service (ENABLE_CALORIE_DB=False): Real-time bidirectional sync deferred; heavy integration code isolated.

They reside in src/_deferred/ and can be re-enabled via flags once scoped for a release milestone.

Runtime/build commands have been deliberately removed (v1.1.2) to prevent distribution of unfinished work. Request internal access: info@calorietoken.net.

📱 Usage

First Time Setup

Launch the app
Choose to create a new wallet or import existing keys
Set up your secure password
Your wallet is ready to use!

Sending Transactions

Navigate to the Wallet screen
Click "Send XRP" or token buttons
Enter recipient address and amount
Confirm transaction

Food Tracking

Access the Food Tracker from the navigation menu
Log your meals and track calories
Monitor your daily nutrition goals

🔧 Development

Project Structure

CalorieAppTestnet/
├── main.py                 # Application entry point
├── run.py                  # Alternative run script
├── buildozer.spec          # Android build configuration
├── requirements.txt        # Python dependencies
├── src/
│   ├── core/
│   │   ├── app.py          # Main application class
│   │   └── kv/                  # Modular KV layout files (replaces monolithic .kv)
│   ├── screens/            # All screen implementations
│   │   ├── WalletScreen.py
│   │   ├── SendXRPScreen.py
│   │   ├── SendTestTokenScreen.py
│   │   ├── MnemonicDisplayScreen.py
│   │   └── ... (25+ screens)
│   └── utils/              # Utility modules
│       ├── xrpl_client_manager.py    # XRPL connectivity
│       ├── conditional_navigation.py # Navigation system
│       ├── mnemonic_manager.py       # BIP39 mnemonic handling
│       ├── password_field_utils.py   # UI utilities
│       ├── robust_transaction.py     # Transaction handling
│       └── token_config.py           # Token configuration
├── assets/                 # App assets and images
│   └── images/            # Logo and UI images
├── config/                 # Configuration files
├── scripts/               # Utility scripts
└── docs/                  # Documentation

Key Components

XRPLClientManager: Handles XRPL connectivity with automatic failover
ConditionalNavigationDrawer: Intelligent navigation system
PasswordFieldWithToggle: Enhanced password input with visibility toggle
robust_submit_and_wait: Transaction submission with retry logic

Development Viewport & Responsive Overrides

During active development and automated UX tours we often want a consistent, phone-sized viewport while still preserving full adaptive behavior for tablets and desktops in production.

Environment overrides (all optional):

Variable	Example	Purpose
`DEV_PHONE_VIEWPORT`	`390x844`	Forces window size (if `APP_FORCE_WIDTH/HEIGHT` not set) to a modern phone logical resolution (portrait enforced).
`FORCE_SIZE_CLASS`	`sm` / `phone`	Pins responsive size class regardless of window width (use `phone` as alias for `sm`).
`TOUR_FORCE_PHONE`	`1`	In UX tour runs auto-sets `DEV_PHONE_VIEWPORT=390x844` and `FORCE_SIZE_CLASS=sm` if unset.
`TOUR_PHONE_WIDTH` / `TOUR_PHONE_HEIGHT`	`414` / `896`	Fine-grained control for UX tour window size when `TOUR_FORCE_PHONE` is enabled.

Example (PowerShell):

$env:DEV_PHONE_VIEWPORT="390x844"; $env:FORCE_SIZE_CLASS="sm"; python -B scripts/complete_ux_tour.py

Production builds simply omit these variables and the app reverts to automatic breakpoint detection (xs, sm, md, lg, xl). The responsive system caches scaling factors to minimize recomputation while keeping layout adjustments correct on window resize.

Breakpoints remain unchanged ensuring cross-platform compatibility; overrides are strictly opt-in for development convenience.

Debug Overlay (Development Only)

Activation mechanics exist but invocation commands are withheld pre-release. Overlay shows breakpoint class, scaling factors, and dimensions when enabled internally.

This displays a small badge in the top-right corner showing:

Current size class (xs/sm/md/lg/xl)
Lock icon (🔒) when FORCE_SIZE_CLASS is active
DP and font scale factors
Current window dimensions

The overlay updates in real-time during window resizes and is automatically removed in production (when DEBUG_RESPONSIVE is unset).

CI Testing Strategy

Automated UX validation runs are supported to help catch regressions across device sizes. Details of internal test tooling are intentionally minimized here for security and competitive reasons. See docs/UX_TOUR_GUIDE.md for a public overview of the process.

🧪 Testing

Automated UX Tour

We use an automated UX tour to validate major screens and flows and to generate visual reports for review. High-level, public-safe documentation is available here:

UX Tour Guide

Implementation details and internal scripts are withheld to protect the project’s integrity until formal release.

UI/UX References (Public)

KivyMD Documentation: https://kivymd.readthedocs.io/
Kivy Documentation: https://kivy.org/doc/stable/
Material Design 3: https://m3.material.io/

Manual Testing

Internal test cycles include navigation, XRPL connectivity/failover simulation, wallet creation/import flows, transaction lifecycle validation, performance sampling, and offline mode handling. Detailed invocation steps are withheld until stable release.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for:

Code style guidelines
Development setup
Testing requirements
Pull request process

📄 License

This project is licensed under a Custom Dual License - see the LICENSE file for details.

Summary:

Personal Use: Permitted for educational, research, and non-commercial purposes
Commercial/Public Use: Requires explicit written permission from CalorieToken

Contact for commercial licensing: info@calorietoken.net

Trademark Notice: CalorieToken® and related branding are registered trademarks. See TRADEMARK.md.

🌐 XRPL Testnet

This application uses the XRPL Testnet for development and testing. Testnet XRP has no real-world value and is used solely for testing purposes.

🔗 Links

Official CalorieToken Resources

Technical Documentation

Trading & Token Info

🆘 Support

For App/Development Issues:

Open an issue on GitHub
Check the documentation
Join Discord Developers Server

For CalorieToken Project:

Built with ❤️ for CalorieToken and the XRPL community

CalorieToken® | Chamber of Commerce KVK: 84216352
Trademark registered with EUIPO | See TRADEMARK.md for usage guidelines

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
assets		assets
data		data
docs		docs
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
main.py		main.py
pyproject.toml		pyproject.toml
requirements.in		requirements.in
requirements.txt		requirements.txt
setup.py		setup.py

Uh oh!

License

CalorieToken/CalorieAppTestnet

Folders and files

Latest commit

History

Repository files navigation

CalorieApp 🍎

⚖️ Legal & Beta Testnet Disclaimer

🪙 CalorieToken Integration

🌟 High-Level Feature Matrix

🛠️ Technical Stack

🏗️ Project Structure

Layout Organization (Modernized)

Conditional Navigation System

XRPL Multi-Server Failover

XRPL Response Caching

🚀 Getting Started (Pre-Release Notice)

⏳ Deferred Components (Isolated)

📱 Usage

First Time Setup

Sending Transactions

Food Tracking

🔧 Development

Project Structure

Key Components

Development Viewport & Responsive Overrides

Debug Overlay (Development Only)

CI Testing Strategy

🧪 Testing

Automated UX Tour

UI/UX References (Public)

Manual Testing

🤝 Contributing

📄 License

🌐 XRPL Testnet

🔗 Links

Official CalorieToken Resources

Technical Documentation

Trading & Token Info

🆘 Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Packages