diff --git a/README.md b/README.md index 1dfbbf6a4..45d2b636a 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,30 @@ -
+
Amethyst Logo -# Amethyst +# Amethyst (Garnet Fork) -## Nostr Client for Android +## Monero-Tipped Nostr Client for Android -Join the social network you control. +A fork of [Amethyst](https://github.com/vitorpamplona/amethyst) with full Monero tipping support, ported from [Garnet](https://github.com/retrnull/garnet). + +Join the social network you control. Send and receive Monero tips — no traces, fully peer-to-peer. [![GitHub downloads](https://img.shields.io/github/downloads/vitorpamplona/amethyst/total?label=Downloads&labelColor=27303D&color=0D1117&logo=github&logoColor=FFFFFF&style=flat)](https://github.com/vitorpamplona/amethyst/releases) [![PlayStore downloads](https://img.shields.io/endpoint?color=green&logo=google-play&logoColor=green&url=https%3A%2F%2Fplay.cuzi.workers.dev%2Fplay%3Fi%3Dcom.vitorpamplona.amethyst%26gl%3DUS%26hl%3Den%26l%3DPlayStore%26m%3D%24shortinstalls)](https://play.google.com/store/apps/details?id=com.vitorpamplona.amethyst) -[![Last Version](https://img.shields.io/github/release/vitorpamplona/amethyst.svg?maxAge=3600&label=Stable&labelColor=06599d&color=043b69)](https://github.com/vitorpamplona/amethyst) +[![Last Version](https://img.shields.io/github/release/vitorpamplona/amethyst.svg?maxAge=3600&label=Stable&labelColor=06599d&color=043b69)](https://github.com/vitorpamplona/amethyst/releases) [![JitPack version](https://jitpack.io/v/vitorpamplona/amethyst.svg)](https://jitpack.io/#vitorpamplona/amethyst) [![CI](https://img.shields.io/github/actions/workflow/status/vitorpamplona/amethyst/build.yml?labelColor=27303D)](https://github.com/vitorpamplona/amethyst/actions/workflows/build.yml) [![License: Apache-2.0](https://img.shields.io/github/license/vitorpamplona/amethyst?labelColor=27303D&color=0877d2)](/LICENSE) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vitorpamplona/amethyst) +### 🔶 Monero Tipping + +This fork adds a complete Monero wallet, tipping engine, and XMR transfer system on top of Amethyst's lightning zap infrastructure. Choose **private** (no traces), **anonymous** (sender hidden, everyone sees tx + message), or **public** (full transparency) tips — just like lightning zaps, but with Monero. + ## Download and Install ### Android @@ -55,6 +61,49 @@ _Coming soon (separate PR): Scoop (Windows), AUR (Arch Linux)._
+## Monero Tipping Engine + +This fork integrates a complete Monero wallet and tipping system, originally developed in [Garnet](https://github.com/retrnull/garnet). + +### How it works + +- A Monero spend key is derived from your Nostr private key. The app has its own wallet that can be funded to send tips. +- A `cryptocurrency_addresses` field is added to **kind 0** (metadata) events, mapping cryptocurrency names (e.g. `"monero"`) to addresses. +- Every post with a tip includes one or more `"monero"` tags — functioning similarly to the lightning zap tag (NIP-57). +- On **every new post**, tips can be sent with one of three privacy levels: + +| Tip Type | Sender Hidden | Transaction Visible | Message Visible | +|----------|:-----------:|:-------------------:|:---------------:| +| **Private** | ✅ | ❌ | ❌ | +| **Anonymous** | ✅ | ✅ | ✅ | +| **Public** | ❌ | ✅ | ✅ | + +- For anonymous and public tips, a tip event (**kind 1814**) is transmitted to your relays. The content is a JSON string containing the txid, message, and a mapping from transaction proofs to addresses. +- Received tips show a counter next to the tip icon on the tipped note, and in the user profile's **"Tips"** tab — just like zaps. +- Received tips can be transferred to an external Monero wallet at any time. + +### Building from source + +In addition to the Amethyst prerequisites, building this fork requires: + +1. Java 17+ +2. Android Studio +3. Android 8.0+ Phone or Emulation setup +4. Docker + +You also need the Monero fork source. Clone it and link it into `external-libs/`: + +```bash +git clone https://github.com/m5/garnet-monero.git +cd garnet-monero +git checkout release-v0.18.3.3-garnet +cd ~/projects/amethyst +ln -s ~/projects/garnet-monero external-libs/monero +git submodule update --init --force +``` + +Then start Docker and run `make`, followed by building the APK in Android Studio. + ## Supported Features @@ -479,31 +528,36 @@ By contributing to this repository, you agree to license your work under the MIT ## Monero Integration Status -An integration of Garnet's Monero tipping/zapping feature was ported against the latest Amethyst codebase. The work lives on the `amethyst-with-monero` branch. +This fork ported all of [Garnet](https://github.com/retrnull/garnet)'s Monero tipping functionality against the latest Amethyst codebase. The port lives on the `amethyst-with-monero` branch. -**What was accomplished (Phase 1-4):** -- Kotlin source code compiles successfully — `compileFdroidDebugKotlin` passes with 0 errors -- Full build passes — `assembleFdroidDebug` builds APKs successfully -- 21 new files (model classes, WalletService, moneroTip events, JNI bridge) + 6 modified files -- WalletService fully implemented (~700 lines) from Garnet source with complete API +### What Garnet provided (original) -**What was accomplished (Phase 5):** -- Wiring complete — MoneroDataSource.setMoneroService() forwards all 7 StateFlows -- 8 new Account methods added (sendMonero, listMoneroAddresses, etc.) -- 8 Account settings properties wired (daemon address, seed, password, restore height, transaction priority) -- MoneroUtils helper functions (showMoneroAmount, decToPiconero) -- TipEventDataSource.getEvent() restored +Garnet was built on an April 2024 Amethyst baseline and added: +- Monero spend key derivation from Nostr private key +- Wallet management with daemon connection, subaddresses, and transaction history +- Three-tip-privacy model: private, anonymous, public +- Kind 1814 tip events with JSON payloads (txid, message, proof mappings) +- Kind 0 `cryptocurrency_addresses` field for Monero address sharing +- Tip counter UI + profile "Tips" tab +- Tip transfer to external wallets +- Full MoneroScreen UI (~1958 lines) -**What was accomplished (MoneroScreen UI):** -- Ported MoneroScreen.kt (~1250 lines) from Garnet's ~1958-line file -- All composables ported: MoneroScreen, MoneroViewModel, MoneroSendViewModel, ReceiveDialog, EditDaemonDialog, Balance, TipInfo, BackupSeedDialog, EphemeralWalletWarning, CustomRestoreHeightDialog, and more -- 47 string resources added for the UI -- `./gradlew assembleFdroidDebug` builds APKs successfully +### Port status (this fork, against latest Amethyst) -**What's remaining:** -- Add `compose-material-icons-extended` dependency (MoneroScreen uses `androidx.compose.material.icons.Icons`) -- Add NIP-69 monero address support -- Full end-to-end testing of monero wallet functionality +| Phase | Status | +|-------|--------| +| **1-4: Model & Service layer** ✅ | 21 new files (Wallet, WalletService, JNI bridge, moneroTip events), 6 modified. WalletService ~700 lines. | +| **5: Wiring** ✅ | MoneroDataSource.setMoneroService() forwards 7 StateFlows. 8 Account methods + 8 settings properties. | +| **MoneroScreen UI** ✅ | Ported to ~1250 lines using Amethyst patterns (MaterialSymbols, context.getString, M3ActionDialog). 47 string resources. | +| **Build** ✅ | `compileFdroidDebugKotlin` — 0 errors. `assembleFdroidDebug` — produces 5 APK variants. | +| **Navigation** 🔄 | MoneroScreen UI is ready but not yet wired into app navigation (Routes.kt / AppNavigation.kt). | + +**Remaining work:** +- Wire MoneroScreen into app navigation +- Add `compose-material-icons-extended` dependency +- Add NIP-69 monero address support for type-0 event sharing +- Full end-to-end testing of wallet creation, daemon connection, and transfers +- Push to Gitea (`gitea.zonehacks.net`) and publish release APKs See [AGENTS.md](./AGENTS.md) for full project notes, build findings, and the merge plan.