chore(docs,ci,build): utils integration + Polkadot stable2503 alignment

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Report a problem in Fearless Wallet Android
+labels: bug
+---
+
+## Summary
+
+What happened? A clear, concise description.
+
+## App & Environment
+
+- App version (Settings → About): 
+- Install source (Play Store / APK / Android Studio): 
+- Device model and Android version: 
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened (include messages, screenshots, or recordings if helpful).
+
+## Logs / Crash
+
+Attach logs or stack traces if available.
+
+## Additional Context
+
+Links, related issues, wallet/network, or account specifics (redact sensitive data).
+

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Community Support (Telegram)
+    url: https://t.me/fearlesshappiness
+    about: Ask general questions and get community help
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for Fearless Wallet Android
+labels: enhancement
+---
+
+## Problem / Motivation
+
+What problem does this solve? Why is it important?
+
+## Proposed Solution
+
+Describe the change. If you have mockups or sketches, attach them.
+
+## Alternatives Considered
+
+Other approaches you thought about.
+
+## Affected Areas
+
+Screens, modules, or flows this touches.
+
+## Additional Context
+
+Links, related issues, or prior art.
+

.github/pull_request_template.md

@@ -0,0 +1,45 @@
+## Summary
+
+Describe the change and why it’s needed.
+
+## Related Issue
+
+Closes #<issue-number> (or) Relates to #<issue-number>
+
+## Type of Change
+
+- [ ] feat (new feature)
+- [ ] fix (bug fix)
+- [ ] refactor (no functional change)
+- [ ] chore/build (tooling, CI, deps)
+- [ ] docs (README/AGENTS, comments)
+
+## Screenshots / Videos
+
+If UI changes, include before/after.
+
+## Test Plan
+
+Commands run locally:
+
+```
+./gradlew detektAll
+./gradlew runTest
+./gradlew :app:lint
+```
+
+Additional checks and scenarios covered:
+- 
+
+## Risks & Rollout
+
+Potential impact, migrations, or config/secrets required.
+
+## Checklist
+
+- [ ] Linked an issue and added a clear description
+- [ ] Added/updated tests for changed code (where applicable)
+- [ ] Updated docs (README/AGENTS) when behavior or commands changed
+- [ ] Ran detektAll, runTest, and :app:lint locally (or via CI)
+- [ ] No secrets or local.properties committed
+

.github/workflows/android-ci.yml

@@ -0,0 +1,109 @@
+name: Android CI
+
+on:
+  pull_request:
+  push:
+    branches: [ master, develop ]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      CI: true
+      USE_REMOTE_UTILS: "true"
+      # Provide safe stubs to avoid repository/config failures during resolution
+      PAY_WINGS_REPOSITORY_URL: https://maven.google.com
+      PAY_WINGS_USERNAME: ""
+      PAY_WINGS_PASSWORD: ""
+      MOONPAY_TEST_SECRET: stub
+      MOONPAY_PRODUCTION_SECRET: stub
+      FL_BLAST_API_ETHEREUM_KEY: stub
+      FL_BLAST_API_BSC_KEY: stub
+      FL_BLAST_API_SEPOLIA_KEY: stub
+      FL_BLAST_API_GOERLI_KEY: stub
+      FL_BLAST_API_POLYGON_KEY: stub
+      FL_ANDROID_ETHERSCAN_API_KEY: stub
+      FL_ANDROID_BSCSCAN_API_KEY: stub
+      FL_ANDROID_POLYGONSCAN_API_KEY: stub
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java 21 (Temurin)
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          packages: |
+            platforms;android-35
+            build-tools;35.0.0
+            platform-tools
+            ndk;25.2.9519653
+
+      - name: Export NDK environment
+        run: |
+          echo "ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.2.9519653" >> $GITHUB_ENV
+          echo "ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/25.2.9519653" >> $GITHUB_ENV
+          echo "NDK_HOME=$ANDROID_SDK_ROOT/ndk/25.2.9519653" >> $GITHUB_ENV
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-linux-android,armv7-linux-androideabi,i686-linux-android,x86_64-linux-android
+
+      - name: Cache cargo registry and builds
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
+      - name: Gradle version
+        run: ./gradlew --version --no-daemon --console=plain --stacktrace
+
+      - name: Static analysis (detekt)
+        run: ./gradlew detektAll --no-daemon --console=plain --stacktrace
+
+      - name: Unit tests + coverage
+        run: ./gradlew runTest --no-daemon --console=plain --stacktrace
+
+      - name: Android Lint (app)
+        run: ./gradlew :app:lint --no-daemon --console=plain --stacktrace
+
+      - name: Gradle/AGP versions
+        run: |
+          echo "== Gradle =="
+          ./gradlew --version --no-daemon --console=plain || true
+          echo "\n== Android Gradle Plugin (declared) =="
+          grep -E '^android_plugin\s*=\s*"[0-9]+' gradle/libs.versions.toml || true
+
+      - name: Assemble debug to produce native libs
+        run: ./gradlew :app:assembleDebug --no-daemon --console=plain --stacktrace
+
+      - name: readelf sanity (native libs)
+        run: |
+          if ! command -v readelf >/dev/null 2>&1; then
+            sudo apt-get update -y && sudo apt-get install -y binutils
+          fi
+          set +e
+          echo "== Scanning native libraries (.so) =="
+          mapfile -t sos < <(find app/build -type f -name "*.so" | head -n 10)
+          if [ ${#sos[@]} -eq 0 ]; then echo "No native libs found under app/build"; exit 0; fi
+          for so in "${sos[@]}"; do
+            echo "\n-- $so --"
+            readelf -l "$so" | sed -n '1,120p' || true
+          done

.gitignore

@@ -12,5 +12,8 @@ app/*.apk
 # ignore jacoco coverage reports
 /coverage
 
+# ignore local logs
+*.log
+
 fearless.jks
-/buildSrc/build
+/buildSrc/build

AGENTS.md

@@ -0,0 +1,87 @@
+# Repository Guidelines
+
+<!-- wallet-context:start -->
+> **About this codebase**  
+> This repository contains the codebase for a cryptocurrency wallet compatible with the **Polkadot**, **EVM**, and **TON** ecosystems.  
+> It uses dependencies available in the [soramitsu/fearless-utils-Android](https://github.com/soramitsu/fearless-utils-Android) repository and has an iOS equivalent in [soramitsu/fearless-iOS](https://github.com/soramitsu/fearless-iOS).
+<!-- wallet-context:end -->
+
+
+[![Android CI](https://github.com/soramitsu/fearless-Android/actions/workflows/android-ci.yml/badge.svg)](https://github.com/soramitsu/fearless-Android/actions/workflows/android-ci.yml)
+
+## Project Structure & Modules
+- `app/`: Android app entry; build types `debug/release/staging/develop/pr`.
+- `feature-*/`: Split by domain with `-api` and `-impl` modules (e.g., `feature-wallet-api`, `feature-wallet-impl`).
+- `core-api/`, `core-db/`, `runtime/`, `runtime-permission/`, `common/`: Shared foundations.
+- `test-shared/`: Test-only utilities reused across modules.
+- `buildSrc/`, `detekt/`, `scripts/`, `docs/`: Gradle plugins/config, static analysis, helper scripts, documentation.
+- Per-module sources: `src/main/java|kotlin`, resources `src/main/res`, unit tests `src/test`, instrumentation tests `src/androidTest`.
+
+## Build, Test, and Dev Commands
+- Build app (APK): `./gradlew :app:assembleDebug` (use `assembleRelease` for release).
+- Full build + checks: `./gradlew clean build`.
+- Static analysis: `./gradlew detektAll` (auto-fix formatting: `./gradlew detektFormat`).
+- Unit tests (aggregated): `./gradlew runTest` (runs detekt, unit tests, JaCoCo report).
+- Per-module unit tests: `./gradlew :core-db:testDebugUnitTest` (or `testDevelopDebugUnitTest` if present).
+- Android Lint: `./gradlew :app:lint`.
+- Coverage report: `./gradlew jacocoTestReport` (outputs under each module’s `build/reports/jacoco`).
+- App version: `./gradlew :app:printVersion`.
+- Local validation helper: `bash scripts/validate-local.sh`.
+
+## Coding Style & Naming
+- Language: Kotlin 2.1, Java 21 target; Compose enabled where applicable.
+- Formatting: Detekt + detekt-formatting; 4-space indent; max line length per `detekt/detekt.yml`.
+- Files: one public class per file; filename matches class (`PascalCase`).
+- Packages: lowercase dot-separated; avoid acronyms.
+- Resources: layouts `activity_*.xml`, `fragment_*.xml`; ids `btnX`, `tvX`; strings `feature_action_label`.
+- KDoc for public APIs; prefer immutable data and explicit visibility.
+
+## Testing Guidelines
+- Frameworks: JUnit4, AndroidX Test, Room testing, Coroutines test; Mockito/MockK available.
+- Structure: unit tests in `src/test`, instrumentation in `src/androidTest`.
+- Naming: mirror class under test, e.g., `AccountRepositoryTest.kt`; methods `fun shouldDoX_whenY()`.
+- Run: module `testDebugUnitTest` (or `testDevelopDebugUnitTest`), or root `runTest`.
+- Coverage: maintain/raise JaCoCo coverage for changed code.
+- New code policy: every time you add a function, create at least one unit test for it (minimum), placed in the corresponding module under `src/test`.
+- Integration (DOT): add instrumentation/integration tests that hit a reachable Polkadot node and log key responses (e.g., runtimeVersion, balances, fees). Guard with assumptions so tests skip when network is unavailable.
+- Logs: when testing DOT, log the raw RPC response and parsed model to aid debugging; never log secrets.
+
+## Commit & Pull Requests
+- Commits: imperative, concise subject; reference issues (`#123`). Prefer Conventional Commits (`feat:`, `fix:`, `refactor:`) when possible.
+- Before PR: ensure `./gradlew runTest` passes and `detektAll` is clean.
+- PR checklist: clear description, linked issue, screenshots/video for UI, steps to test, notes on config/secrets.
+ - Use the PR template; CI must be green (Android CI badge above).
+
+## Security & Configuration
+- Secrets are read via `scripts/secrets.gradle`; set in env vars or `local.properties` (see `README.md`).
+- Do not commit keys or `local.properties`. Use the provided debug keystore only for local builds.
+- Polkadot runtime sources: to align with a specific Polkadot SDK release (e.g., `polkadot-stable2503`), you can override chain/type registries without code changes:
+  - `TYPES_URL_OVERRIDE`, `DEFAULT_V13_TYPES_URL_OVERRIDE`, `CHAINS_URL_OVERRIDE`
+  - Example in `local.properties`:
+    - `TYPES_URL_OVERRIDE=https://.../all_chains_types_android.json`
+    - `CHAINS_URL_OVERRIDE=https://.../chains.json`
+  - After updating, run `./gradlew detektAll runTest :app:lint`.
+- Library version pinning: to use a specific `shared_features` version compatible with a Polkadot SDK release, set
+  - `SHARED_FEATURES_VERSION_OVERRIDE=1.x.y`
+  - Works via `local.properties` or environment variable.
+
+## Local Properties (private)
+- Create a root-level `local.properties` with the required secrets and service credentials. Do NOT commit this file.
+- See `docs/samples/local.properties.example` and create a private `local.properties` at the repo root; replace placeholders with your real values.
+- Typical keys include: MoonPay, PayWings (Sora Card), X1 plugin, Google Web Client IDs, Ethereum providers (Blast, Etherscan/BscScan/PolygonScan/OKLink), WalletConnect, Alchemy, Dwellir, TON API.
+- Formats: use `key=value` per line; avoid trailing spaces. Strings may be unquoted; if values contain special characters or spaces, wrap in double quotes. Set `sdk.dir=/absolute/path/to/Android/sdk` to avoid SDK lookup errors.
+- Runtime overrides (mirrors recommended for first run):
+  - `TYPES_URL_OVERRIDE=https://cdn.jsdelivr.net/gh/soramitsu/shared-features-utils@master/chains/all_chains_types_android.json`
+  - `DEFAULT_V13_TYPES_URL_OVERRIDE=https://cdn.jsdelivr.net/gh/soramitsu/shared-features-utils@master/chains/default_v13_types.json`
+  - `CHAINS_URL_OVERRIDE=https://cdn.jsdelivr.net/gh/soramitsu/shared-features-utils@master/chains/v13/chains.json`
+- Verify config: `./gradlew printPolkadotSdkAlignment` prints effective URLs and any shared_features pin before you run the app/tests.
+
+## Utils Integration
+- Gradle maps the GitHub repo `soramitsu/fearless-utils-Android` as a source dependency and builds `jp.co.soramitsu.fearless-utils:fearless-utils` from source (requires network).
+- Building from source requires NDK and Rust toolchain installed (see README for versions).
+- This enables rapid testing of utils updates needed for specific Polkadot SDK releases.
+
+## Documentation
+- Status: see `docs/status.md` for current health, coverage, and risks.
+- Roadmap: see `docs/roadmap.md` for prioritized tasks, acceptance criteria, and prompts.
+- Sync policy: update `docs/status.md` and `docs/roadmap.md` whenever code changes (in the same PR) so they stay in sync with the repository’s current state.

CONTRIBUTING.md

@@ -3,6 +3,8 @@
 
 Welcome to Android repository of Fearless Wallet application. If you would like to help us to make the best wallet in Polkadot/Kusama ecosystem, please find appropriate section which describes how you can help us.
 
+For developer setup, module structure, commands, and coding conventions, see the Contributor Guide in [AGENTS.md](AGENTS.md). It complements this document with practical instructions for building, testing, and submitting PRs.
+
 ### 🐞 Reporting bugs
 
 In case you have found any issues with an existing app, feel free to report it directly to [Issues board](https://github.com/soramitsu/fearless-Android/issues). In your report please mention following data:

README.md

@@ -1,5 +1,5 @@
 ### Fearless Wallet Android
-[![Google Play](https://img.shields.io/badge/Google%20Play-Android-green?logo=google%20play)](https://play.google.com/store/apps/details?id=jp.co.soramitsu.fearless)
+[![Google Play](https://img.shields.io/badge/Google%20Play-Android-green?logo=google%20play)](https://play.google.com/store/apps/details?id=jp.co.soramitsu.fearless) [![Android CI](https://github.com/soramitsu/fearless-Android/actions/workflows/android-ci.yml/badge.svg)](https://github.com/soramitsu/fearless-Android/actions/workflows/android-ci.yml)
 
 ![logo](/docs/fearlesswallet_promo.png)
 
@@ -14,6 +14,13 @@ Fearless Wallet roadmap is available for everyone: [roadmap link](https://sorami
 ## Dev Status
 Track features development: [board link](https://soramitsucoltd.aha.io/shared/343e5db57d53398e3f26d0048158c4a2)
 
+## Architecture & Current State
+- Architecture overview: see `docs/ARCHITECTURE.md` for module layout, layers, and flows.
+- Module map: see `docs/MODULES.md` for a quick feature-by-feature guide.
+- Current state: see `docs/CURRENT_STATE.md` for supported ecosystems, integrations, and TODO hotspots.
+ - Status snapshot: see `docs/status.md` for health, risks, and what’s incomplete.
+ - Roadmap: see `docs/roadmap.md` for prioritized, actionable tasks.
+
 ## How to build
 
 To build Fearless Wallet Android project, you need to provide several keys either in environment variables or in `local.properties` file:
@@ -85,5 +92,41 @@ FL_ANDROID_BSCSCAN_API_KEY
 FL_ANDROID_POLYGONSCAN_API_KEY
 ````
 
+## Local Validation
+
+Run static analysis, unit tests, lint, and set up Android SDK packages:
+
+```
+bash scripts/validate-local.sh
+```
+
+Manual equivalents if you prefer:
+
+```
+./gradlew detektAll
+./gradlew runTest
+./gradlew :app:lint
+```
+
+Prerequisites: JDK 21 (Temurin/Adoptium) and Android SDK with API 35 + build-tools 35.0.0. The script will try to locate `ANDROID_SDK_ROOT` and install missing packages if `sdkmanager` is available.
+
+### Use fearless-utils-Android (remote source dependency)
+
+The build maps the GitHub repository as a source dependency and builds the module from source.
+
+```
+# Requires network access during Gradle configuration
+./gradlew :app:assembleDebug
+```
+
+Gradle will fetch https://github.com/soramitsu/fearless-utils-Android and build module `jp.co.soramitsu.fearless-utils:fearless-utils` from source.
+
+Prereqs for building the utils from source: NDK (25.2.9519653) and Rust toolchain available on PATH (`rustup`, `cargo`).
+
+## Contributing
+
+- Contributor Guide: see [AGENTS.md](AGENTS.md) for project layout, commands, and conventions.
+- Process & community details: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 Fearless Wallet Android is available under the Apache 2.0 license. See the LICENSE file for more info.