Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

14.2 KB
Raw Blame

solana-mobile/: the three.ws Android app

Everything needed to package three.ws as an Android app and publish it: the Mobile Wallet Adapter (MWA) wallet that signs through the on-device Seed Vault, the Trusted Web Activity (TWA) wrapper, the release pipeline, and the listing copy for both stores.

Next: v1.1.0 (versionCode 2) adds the Agent glance home screen widget (../docs/native-widgets.md); it is built and emulator-verified (2026-08-29) and ships once its API lane is deployed.

Status: v1.0.0 approved and live on the Solana dApp Store (submitted 2026-08-28, approved 2026-09-01) (release #331044442814, versionCode 1). The reviewed bytes are the v1.0.0 GitHub release. Identifiers and what the portal recorded: ../docs/seeker-submission-day.md.

One package id, two channels. ws.three.app ships to the Solana dApp Store (Seeker and Saga, listing copy in publish/) and to Google Play (every Android phone, listing copy and submission runbook in publish-play/). Same build, same app, two store listings that must describe the same product. The Play path has one trap with no local symptom, and it is documented in publish-play/README.md step 6: Play re-signs the bundle with Google's own key, so Google's certificate fingerprint has to be added to twa/extra-fingerprints.json or every Play install loses full-screen mode.

Layout

solana-mobile/
├── twa/twa-manifest.json     # Bubblewrap input: wraps three.ws as an Android TWA
├── well-known/               # assetlinks.json template (real file: /public/.well-known/)
├── src/                      # MWA wallet wrapper (drop-in for the existing Solana code)
│   ├── seeker-detect.js      #   TWA/Seeker detection + isMwaSupported() capability probe
│   ├── mwa-wallet.js         #   Phantom-shaped wallet backed by the on-device Seed Vault
│   ├── mwa-errors.js         #   normalizes MWA errors (user decline -> code 4001)
│   ├── index.js              #   single-import boot; sets window.solana when on Seeker
│   └── package.json          #   declares MWA peer/runtime deps
│   └── extra-fingerprints.json # certificates OTHER than our keystore that may sign the app
├── scripts/
│   ├── setup-android-sdk.sh  # headless machines: stage JDK 17 + Android SDK for Bubblewrap
│   ├── build-apk.sh          # generate keystore (if needed), build + sign release APK
│   ├── assetlinks.mjs        # build the Digital Asset Links file from every signing certificate
│   ├── make-media.mjs        # generate icon/banner/feature listing assets from the live product
│   ├── update-assetlinks.sh  # refresh /public/.well-known/assetlinks.json from the keystore
│   └── publish.sh            # upload the APK to the Publisher Portal (dapp-store-cli 1.x)
├── publish/                  # Solana dApp Store: Publisher Portal worksheet + listing + media
│   ├── config.yaml           #   every value the owner enters in the portal, in one place
│   ├── listing/              #   description, short description, what's new, Seeker features
│   └── media/                #   icon, banner, feature graphic (screenshots need a real Seeker)
├── publish-play/             # Google Play: submission runbook, worksheet, listing, declarations
│   ├── README.md             #   the account-type decision that sets the timeline, then the steps
│   ├── config.yaml           #   every value the owner enters in Play Console
│   └── listing/              #   title/short/full copy, data safety, content rating, financial features
└── docs/
    ├── ASSETS.md             # exact pixel specs for icon/banner/screenshots
    ├── CHECKLIST.md          # end-to-end submission checklist with verification dates
    └── INTEGRATION.md        # how the wallet is wired into the three.ws bundle

The web manifest is NOT duplicated here: the live one is generated by vite-plugin-pwa from vite.config.js (webManifestUrl in twa/twa-manifest.json points at it). The app-only surfaces live with the rest of the site:

  • /seeker (pages/seeker.html, src/seeker.js): the TWA's start URL. One-tap Seed Vault sign-in, Create / Explore grid, the owner's agents, and Seeker Genesis Token verification.
  • Share target: public/share-target-sw.js handles POST /create/share from the Android share sheet; src/shared/share-target.js hands the file to /create/selfie (photos) or /create (GLB). The APK registers the same target through shareTarget in twa/twa-manifest.json (MIME types only; Android rejects file extensions there).
  • Offline: public/offline.html is precached and served by the workbox precacheFallback rule in vite.config.js when a navigation fails.
  • Icons: public/pwa-maskable-*.png keep the glyph inside Android's safe zone; build-apk.sh serves public/ locally during the build so the APK embeds this commit's icons rather than whatever the last deploy shipped.
  • Seeker verification API: api/seeker/[action].js, documented in docs/api-reference.md. Product doc: docs/seeker-app.md.

How the wallet works

The MWA wallet is already wired into the bundle: src/wallet.js and src/game/play-auth.js import solana-mobile/src/index.js, and @solana-mobile/mobile-wallet-adapter-protocol-web3js is a root dependency. Inside the TWA the import installs an MwaWallet at window.threeWsWallet (mirrored onto window.solana); everywhere else it is a no-op. src/onchain/adapters/solana.js uses the Seed Vault's one-tap Sign-In With Solana (signIn()) for wallet linking and falls back to the two-step signMessage flow on injected wallets.

The MWA auth token is persisted in localStorage (with a sessionStorage fallback), so a session survives Android killing the backgrounded TWA process: the next signature is a silent reauthorize, not a new Seed Vault prompt. A token the wallet has revoked is dropped on the first failed reauthorize and the wallet emits disconnect. The wrapper is unit-tested against a fake transport:

npx vitest run tests/solana-mobile-mwa-wallet.test.js \
  tests/solana-mobile-mwa-errors.test.js tests/solana-mobile-seeker-detect.test.js

Details: docs/INTEGRATION.md.

Release pipeline

The full runbook, including the Publisher Portal steps the owner does once, is docs/seeker-publishing.md. The short version:

Publishing is Publisher Portal backed (dapp-store-cli 1.0, May 2026). The publisher profile, KYC, the App NFT, and the listing live in https://publish.solanamobile.com; the CLI only uploads one signed APK per release and the portal matches it to the app by package name (ws.three.app).

cd solana-mobile

# 0. Headless machine (codespace/container) with no Android toolchain yet:
#    stages JDK 17 + Android SDK under ~/.bubblewrap. Idempotent.
./scripts/setup-android-sdk.sh

# 1. Restore the release keystore (it is gitignored). Both halves live in
#    Secret Manager since 2026-08-27; the password also sits in .env as
#    SOLANA_MOBILE_KEYSTORE_PASSWORD. Losing this key means the app can never
#    be updated, so never generate a second one while this one exists.
gcloud secrets versions access latest --secret three-ws-seeker-release-keystore \
  --project aerial-vehicle-466722-p5 | base64 -d > android.keystore
export SOLANA_MOBILE_KEYSTORE_PASSWORD="$(gcloud secrets versions access latest \
  --secret three-ws-seeker-keystore-password --project aerial-vehicle-466722-p5)"

# 2. Build the signed APK. Also writes /public/.well-known/assetlinks.json
#    with the key's fingerprint (98:0A:1A:AB:...:11:13:D7).
KEYSTORE_PASSWORD="$SOLANA_MOBILE_KEYSTORE_PASSWORD" ACCEPT_ANDROID_SDK_LICENSES=1 ./scripts/build-apk.sh

# 3. Deploy three.ws so assetlinks.json is live (npm run deploy:gcp from the
#    repo root; production is Cloud Run), then confirm Google sees it:
curl -fsSL https://three.ws/.well-known/assetlinks.json | jq .
curl -fsSL 'https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://three.ws&relation=delegate_permission/common.handle_all_urls'

# 4. First release only, in the portal (owner): create the publisher profile,
#    pass KYC/KYB, "Add a dApp" using publish/config.yaml + publish/listing/ +
#    publish/media/, mint the App NFT (~0.2 SOL in the publisher wallet), and
#    create an API key under Settings > API keys.

# 5. Submit the release.
SOLANA_KEYPAIR=~/.config/solana/publisher.json \
DAPP_STORE_API_KEY='portal-api-key' \
./scripts/publish.sh

For later releases, bump appVersionCode / appVersion in twa/twa-manifest.json (or pass VERSION_CODE / VERSION_NAME), then repeat steps 2 and 5. publish.sh refuses to re-submit a versionCode it already shipped from the same machine. Releases are run locally by the owner; this repo does not use GitHub Actions.

Emulator QA

Everything except the Seed Vault itself can be verified in a stock emulator; this is how the 2026-08-27 build was checked.

# One-time: emulator, platform tools, and an Android 14 image (KVM needed: sudo chmod 666 /dev/kvm in a codespace).
SDK=~/.bubblewrap/android_sdk/cmdline-tools
$SDK/bin/sdkmanager --sdk_root=$SDK "platform-tools" "emulator" "build-tools;34.0.0" "system-images;android-34;google_apis;x86_64"
echo no | $SDK/bin/avdmanager create avd -n seeker -k "system-images;android-34;google_apis;x86_64" -d pixel_7
# The SDK root is the cmdline-tools dir, so fix the image path avdmanager writes:
sed -i 's#^image.sysdir.1=.*#image.sysdir.1=system-images/android-34/google_apis/x86_64/#' ~/.android/avd/seeker.avd/config.ini
ANDROID_SDK_ROOT=$SDK $SDK/emulator/emulator -avd seeker -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect &

adb install -r build/three-ws-release.apk
adb shell am start -n ws.three.app/.LauncherActivity        # first launch shows Chrome's welcome sheet once
adb shell dumpsys shortcut | grep -A40 "Package: ws.three.app" | grep shortLabel
adb shell pm get-app-links ws.three.app                     # state 1 after assetlinks.json is live for this key
adb push ../public/pwa-512x512.png /sdcard/Download/selfie.png
adb shell am start -a android.intent.action.SEND -t image/png \
  --eu android.intent.extra.STREAM file:///sdcard/Download/selfie.png -n ws.three.app/.LauncherActivity --grant-read-uri-permission
adb exec-out screencap -p > shot.png

Until the commit that adds /seeker and the share handler is deployed, the emulator opens production and shows the site's 404 for both; that is the deploy gate, not an app bug.

The home screen widget

The release APK fetches its card from https://three.ws, so a widget in a release build shows "Fetching your agent" until /api/glance/mine?format=png is deployed. To exercise the whole loop against a local server before that, build the debug variant of the same overlaid project (only the debug variant allows plain http and honours the origin override; see android-overlay/app/src/debug/AndroidManifest.xml) and link it with a real token:

# After scripts/build-apk.sh (which applies android-overlay/ to build/):
(cd build && JAVA_HOME=~/.bubblewrap/jdk/jdk-17.0.20.1+1 ./gradlew assembleDebug -q)
adb install -r build/app/build/outputs/apk/debug/app-debug.apk

# A local API on :8080 (from the repo root: PORT=8080 node --env-file=.env --env-file=.env.local server/index.mjs),
# a session for the QA account, and a widget token from it:
TOKEN=$(curl -s -c /tmp/j -H 'content-type: application/json' -H 'origin: https://three.ws' \
  -d "{\"email\":\"$AUDIT_EMAIL\",\"password\":\"$AUDIT_PASSWORD\"}" http://127.0.0.1:8080/api/auth/login >/dev/null && \
  curl -s -b /tmp/j -H 'content-type: application/json' -H 'origin: https://three.ws' \
  -d '{"platform":"android","label":"emulator"}' http://127.0.0.1:8080/api/glance/token | jq -r .token)

# Link the widget (the inner quotes keep the & away from the emulator's shell) and accept the launcher's pin dialog:
adb shell am start -a android.intent.action.VIEW -d "'threews://glance/link?token=$TOKEN&origin=http://10.0.2.2:8080'"
adb shell uiautomator dump /sdcard/ui.xml && adb shell cat /sdcard/ui.xml | grep -o 'text="Add to home screen"[^>]*bounds="[^"]*"'   # then `adb shell input tap` inside those bounds

# The five checks (the widget lands on home screen page 2; `input swipe 900 1200 200 1200 300` gets there):
adb logcat -d | grep WM-WorkerWrapper                                   # SUCCESS: refreshed with no app UI open
adb shell run-as ws.three.app ls -la files/glance                        # the cached bitmap per size
adb shell am force-stop ws.three.app                                     # widget keeps its card
adb shell cmd connectivity airplane-mode enable                          # then tap "Updated …" on the widget: footer says "(offline)", card stays
adb reboot && adb wait-for-device                                        # widget comes back with its card

uiautomator dump is the reliable way to read the widget's state headless: the card ImageView carries a content description of ", " and the footer TextView (ws.three.app:id/glance_updated) carries the refresh time.

What still needs a physical Seeker

Listing media is no longer on that list. Everything the portal asks for is generated and checked in under publish/media/: npm run build:dapp-store-media writes the icon, banner, feature graphic, and the 1200x1200 Editor's Choice card, and npm run build:dapp-store-previews builds the five 1080x1920 previews as one carousel (see docs/ASSETS.md). Real Seeker captures dropped into publish/media/device/ replace the browser ones and the carousel rebuilds around them.

  • Device smoke (install, Seed Vault sheet, suspend/resume, deep links): section 3, 4, and 9 of docs/CHECKLIST.md.
  • Promo video: optional; publish/media/video.mp4 if ever added.

Privacy policy and EULA are content of the main site and are live at /legal/privacy and /legal/eula.

See also