Setup Guide

RavenTag is fully self-hosted and brand-sovereign. Once deployed, your infrastructure is independent from RavenTag.io.

┌──────────────────────┐    ┌─────────────────────────────┐
│  RavenTag.io         │    │  Your Brand Infrastructure   │
│  • Public brand list │◄───│  Brand Backend (Docker)      │
│  • Docs / Downloads  │    │  • BRAND_MASTER_KEY (secret) │
└──────────────────────┘    │  • ADMIN_KEY / OPERATOR_KEY  │
                            └──────────┬──────────────────┘
                                       │
┌──────────────────────┐    ┌──────────▼──────────────────┐
│  Brand Manager App   │◄───│  Ravencoin Node              │
│  Admin / Operator    │    │  (asset issuance, wallet)    │
└──────────────────────┘    └─────────────────────────────┘
┌──────────────────────┐
│  Consumer Verify App │  ← your branded app
└──────────────────────┘

The brand backend is Node.js + Express. Deploy it on any server or cloud.

git clone https://github.com/ALENOC/RavenTag.git && cd RavenTag
cp backend/.env.example backend/.env
# Edit .env , set BRAND_NAME, ADMIN_KEY, BRAND_MASTER_KEY, BRAND_SALT
docker compose up backend

When the backend starts with BRAND_NAME set, it automatically registers in the public RavenTag brand directory.

# backend/.env
BRAND_NAME=Fashionx

# On startup:
# [Registry] Brand "Fashionx" registered in RavenTag public registry.

Get the wallet address from the Brand App (Wallet → Receive) or admin dashboard. The app uses a local BIP44 HD wallet.

Two access levels allow separation between brand managers and factory operators who program tags.

ADMIN_KEY=secret-key
X-Admin-Key: secret-key

OPERATOR_KEY=op-key
X-Operator-Key: op-key

Create your asset hierarchy. The typical structure for serialized products:

FASHIONX              ← Root asset (500 RVN)
FASHIONX/BAG01        ← Sub-asset (100 RVN)
FASHIONX/BAG01#SN0001 ← Unique token (5 RVN) , one per physical item

Fully white-label the Consumer App for your brand. Edit one file, replace logos, compile.

Step 1, Edit AppConfig.kt

// android/app/src/consumer/java/io/raventag/app/config/AppConfig.kt
object AppConfig {
    const val IS_BRAND_APP = false
    const val BRAND_NAME = "Fashionx"
    const val DEFAULT_VERIFY_URL = "https://verify.fashionx.com"
    const val PRIMARY_COLOR_HEX = "#C9622D"
    const val LOGO_DRAWABLE = "raven_logo"
}

Step 2, Replace logos

android/app/src/main/res/drawable/raven_logo.jpg   # In-app header logo
android/app/src/main/res/drawable/ic_app_logo.jpg  # App icon source

Step 3, Build & distribute

./gradlew assembleConsumerRelease
# APK: app/build/outputs/apk/consumer/release/app-consumer-release.apk

Consumer taps NFC chip
  → Consumer App reads URL: https://verify.yourbrand.com/verify?asset=...&e=...&m=...
  → Backend decrypts e → UID + counter
  → Verifies MAC: CMAC(sdmMacKey, e)[even_bytes][:4] == m
  → Checks counter > stored (anti-replay)
  → Ravencoin → IPFS → nfc_pub_id match
  → Revocation check
  → Returns: { authentic: true/false, revoked: false }

# Via API (immediate, reversible):
POST /api/brand/revoke
X-Admin-Key: your-key
{ "asset_name": "FASHIONX/BAG01#SN0001", "reason": "Stolen", "burn_on_chain": false }

# Un-revoke: DELETE /api/brand/revoke/FASHIONX%2FBAG01%23SN0001
# Burn on-chain (IRREVERSIBLE): { ..., "burn_on_chain": true }

Attach a product image to an asset by tapping the image picker in the Issue Asset screen. The image is uploaded to your IPFS node and the CID is stored in the Ravencoin asset metadata.

// In Brand App → Issue Asset screen:
// 1. Tap image picker → select photo from gallery or camera
// 2. App uploads to IPFS node: POST http://127.0.0.1:5001/api/v0/add
// 3. CID stored in asset metadata: { "image": "ipfs://QmXxx..." }
// 4. Ravencoin asset metadata includes IPFS hash on-chain

After creating a wallet, the app displays the 12-word mnemonic phrase exactly once on a mandatory backup screen. Write it down offline and keep it safe, it is the only way to recover your wallet.

// BIP44 derivation path: m/44'/175'/0'/0/0
// Coin type 175 = Ravencoin (SLIP-0044)
// 12-word BIP39 mnemonic → deterministic private key + address
// Private key encrypted in Android Keystore (StrongBox/TEE)

// Restore: Brand App → Create/Restore Wallet → Restore
// Enter 12 words → same address generated on any BIP39 wallet

Common issues and solutions.