# Plan: Integrate Garnet (Monero Tipping) into Latest Amethyst

## Status

| Phase | Name | Status |
|---|---|---|
| 1 | Investigation | **COMPLETE** |
| 2 | Native Libraries | **COMPLETE** |
| 3 | Model + Service Layer | **COMPLETE** |
| 4 | Quartz Events (KMP) | **COMPLETE** |
| 5 | UI Layer | **IN PROGRESS** |
| 6 | Resources + Build Config | **COMPLETE** |
| 7 | Build and Verify | **COMPLETE** (BUILD SUCCESSFUL) |

---

## Key Discoveries

During the port, these breaking changes from Garnet (based on amethyst April 2024) were discovered:

| Garnet Assumption | Reality in Latest Amethyst |
|---|---|
| `NostrSigner.sign()` uses callback | `NostrSigner.sign()` is **coroutine-based** (`suspend`) |
| `Note`, `User` in `amethyst.model` | Moved to **`commons.model`** (KMP shared) |
| `HexKey` from `nip01Core.encoders` | Now at **`nip01Core.core`** |
| `KeyPair` from `nip01Core.crypto` | Now at **`nip01Core.crypto`** (same path but different module layout) |
| `User` metadata via getter method | **StateFlow-based** (`userMetadataFlow`) |
| `LocalCache.consume()` takes 2 args | Now takes **3 args** (type, filter, callback) |
| `TransactionPriority` in model/service | Lives in **`ui/screen/loggedIn`** as an enum |
| Application context access pattern | `Amethyst.instance.appContext` (not `applicationContext`) |
| TipSplit setup as class/inline | **Extension function** on `Event?`: `tipSplitSetup()` |

---

## What's Done (Phases 1-4, 6-7)

### New files created (18):

**Model layer** (`amethyst/src/main/java/.../model/`):
- `MoneroWalletListener.kt` — Listens to Monero wallet events
- `Wallet.kt` — Wallet data class
- `WalletManager.kt` — Wallet lifecycle manager
- `PendingTransaction.kt` — Pending tx data class
- `ProofInfo.kt` — Tip proof info data class
- `Subaddress.kt` — Subaddress management
- `Transaction.kt` — Transaction data class
- `TransactionHistory.kt` — Transaction history
- `TransactionInfo.kt` — Transaction info
- `Transfer.kt` — Transfer data class

**Service layer** (`amethyst/src/main/java/.../service/`):
- `MoneroDataSource.kt` — Monero data access
- `TipEventDataSource.kt` — Tip event CRUD
- `TipHandler.kt` — Tip event handling logic
- `WalletService.kt` — Wallet service (702 lines)

**Quartz events** (`quartz/src/commonMain/kotlin/.../`):
- `moneroTip/MoneroTipEvent.kt` — Kind 1814 Monero tip event
- `moneroTip/TipSplitSetup.kt` — Tip split setup extension function on `Event?`

**Other**:
- `TransactionPriority.kt` (`ui/screen/loggedIn/`) — Transaction priority enum
- `monero.xml` (`res/drawable/`) — Monero icon
- `wallet2_api.h` (`cpp/`) — Monero wallet API header

### Existing files modified (7):

| File | Changes |
|---|---|
| `Account.kt` | Added `moneroSpendKeyFlow`, `moneroSeedFlow`, `moneroRestoreHeightFlow`, `moneroPasswordFlow` + derivation logic + `moneroAddressIsValid()` |
| `User.kt` (commons) | Added monero address extraction from metadata |
| `UserMetadataCache.kt` (commons) | Added monero metadata field |
| `EventFactory.kt` (quartz) | Added `MoneroTipEvent` import + parsing in factory |
| `TransactionPriority.kt` | New enum (31 lines) |
| `strings.xml` | Added ~53 monero-specific strings |
| `build.gradle.kts` | Added JNA dependency for monero JNI |

### Native libraries (in jniLibs, gitignored):

Prebuilt from garnet v0.3.0 APK, placed in 3 ABIs (arm64-v8a, armeabi-v7a, x86_64):
- `libmonerujo.so` — Monero JNI bridge
- `libsodium.so` — Cryptographic library
- `libjnidispatch.so` — JNI dispatch
- `libc++_shared.so` — C++ runtime
- `libsecp256k1-jni.so` — secp256k1

### Build verification

```
BUILD SUCCESSFUL in 40s (116 tasks)
```

---

## What's Next: Phase 5 - UI Layer (In Progress)

Garnet had ~20+ UI files. Here is the full list — what needs to be created vs modified.

### New UI files to create (11):

**Create (high priority):**

| Garnet Source | Destination |
|---|---|
| `MoneroScreen.kt` | `amethyst/.../ui/screen/loggedIn/` |
| `TipFeedState.kt` | `amethyst/.../ui/screen/` |
| `TipFeedView.kt` | `amethyst/.../ui/screen/` |
| `TipFeedViewModel.kt` | `amethyst/.../ui/screen/` |

**Create (medium priority):**

| Garnet Source | Destination |
|---|---|
| `TipNoteCompose.kt` | `amethyst/.../ui/note/` |
| `TipUserSetCompose.kt` | `amethyst/.../ui/note/` |
| `DisplayTipSplits.kt` | `amethyst/.../ui/note/elements/` |
| `UpdateTipAmountDialog.kt` | `amethyst/.../ui/note/` |
| `TipCustomDialog.kt` | `amethyst/.../ui/note/` |
| `UserProfileTipsFeedFilter.kt` | `amethyst/.../ui/dal/` |

### Existing files that need modification:

| File | Changes needed |
|---|---|
| `Routes.kt` | Add monero route |
| `AppNavigation.kt` | Add monero navigation |
| `AppTopBar.kt` | Add monero icon/button |
| `MainScreen.kt` | Add monero screen |
| `NoteCompose.kt` | Integrate monero tips display |
| `ReactionsRow.kt` | Add monero tip reactions |
| `ProfileScreen.kt` | Add monero tips tab |
| `NewPostView.kt` / `NewPostViewModel.kt` | Add monero tag to new posts |

### Material3 API changes to apply:

- Replace `rememberRipple(Boolean, Dp, Color)` → use `LocalRippleInfo.current`
- Replace `autoCorrect` parameter → check current TextField API
- Adapt to any Compose parameter changes since Garnet wrote them

### Kotlin 2.x / Coroutines changes to keep in mind:

- `NostrSigner.sign()` is `suspend` — all callers must be coroutines
- StateFlow-based `User.metadata` — use subscription instead of direct access
- `LocalCache.consume()` takes 3 args — update signatures

---

## Files Complete

### New files to create (total):
- `amethyst/src/main/java/.../model/MoneroWalletListener.kt` ✓
- `amethyst/src/main/java/.../model/Wallet.kt` ✓
- `amethyst/src/main/java/.../model/WalletManager.kt` ✓
- `amethyst/src/main/java/.../model/PendingTransaction.kt` ✓
- `amethyst/src/main/java/.../model/ProofInfo.kt` ✓
- `amethyst/src/main/java/.../model/Subaddress.kt` ✓
- `amethyst/src/main/java/.../model/Transaction.kt` ✓
- `amethyst/src/main/java/.../model/TransactionHistory.kt` ✓
- `amethyst/src/main/java/.../model/TransactionInfo.kt` ✓
- `amethyst/src/main/java/.../model/Transfer.kt` ✓
- `amethyst/src/main/java/.../service/MoneroDataSource.kt` ✓
- `amethyst/src/main/java/.../service/TipEventDataSource.kt` ✓
- `amethyst/src/main/java/.../service/TipHandler.kt` ✓
- `amethyst/src/main/java/.../service/WalletService.kt` ✓
- `amethyst/src/main/java/.../ui/screen/loggedIn/MoneroScreen.kt`
- `amethyst/src/main/java/.../ui/screen/TipFeedState.kt`
- `amethyst/src/main/java/.../ui/screen/TipFeedView.kt`
- `amethyst/src/main/java/.../ui/screen/TipFeedViewModel.kt`
- `amethyst/src/main/java/.../ui/components/Tip.kt`
- `amethyst/src/main/java/.../ui/note/TipCustomDialog.kt`
- `amethyst/src/main/java/.../ui/note/TipNoteCompose.kt`
- `amethyst/src/main/java/.../ui/note/TipUserSetCompose.kt`
- `amethyst/src/main/java/.../ui/note/UpdateTipAmountDialog.kt`
- `amethyst/src/main/java/.../ui/note/elements/DisplayTipSplits.kt`
- `amethyst/src/main/java/.../ui/dal/UserProfileTipsFeedFilter.kt`
- `amethyst/src/main/java/.../ui/screen/loggedIn/TransactionPriority.kt` ✓
- `quartz/src/commonMain/.../moneroTip/MoneroTipEvent.kt` ✓
- `quartz/src/commonMain/.../moneroTip/TipSplitSetup.kt` ✓

### Files modified (total):
- `Account.kt` ✓ — Monero address management (spend key, seed, password flows)
- `User.kt` (commons) ✓ — Monero address from type-0 event
- `UserMetadataCache.kt` (commons) ✓ — Monero metadata field
- `LocalCache.kt` — (not needed, User handles metadata)
- `LocalPreferences.kt` — (not needed, Account handles prefs directly)
- `Note.kt` — Add monero tag extraction (type-0 metadata)
- `ServiceManager.kt` — (wallet lifecycle now in WalletService)
- `EventFactory.kt` (quartz) ✓ — MoneroTipEvent factory
- `Event.kt` (quartz) — Monero metadata extraction (if needed separately from EventFactory)
- `Routes.kt` — Add monero route
- `AppNavigation.kt` — Add monero navigation
- `AppTopBar.kt` — Add monero icon
- `MainScreen.kt` — Add monero screen
- `NoteCompose.kt` — Display monero tips
- `ReactionsRow.kt` — Monero tip reactions
- `ProfileScreen.kt` — Monero tips tab
- `NewPostView.kt` / `NewPostViewModel.kt` — Add monero tags
- `strings.xml` ✓ — Monero strings
- `build.gradle.kts` ✓ — JNA dependency
- `monerujo.cpp`, `monerujo.h` (cpp) ✓ — Native bridge
- `wallet2_api.h` (cpp) ✓ — Monero API header
- `monero.xml` (drawable) ✓ — Icon