ADAMANT Notification Service (ANS)

Configuration

1. Fill config5.json file with configuration settings (config.sample.json5 as an example)
2. Create firebase-credentials.json file (firebase-credentials.example.json as an example)
3. pnpm install
4. export DATABASE_URL=$database-url
5. npx prisma migrate deploy
6. pnpm run build
7. pnpm run start

How it works

To deliver notifcations privately and secure, 4 parties are involved:

1. User's device (Android or iOS)
2. ADAMANT node
3. Apple Push Notification Service (APNS), for iOS, or Firebase Cloud Messaging (FCM), for Android
4. This application, ADAMANT Notification Service (ANS)

A workflow runs as:

• User's device requests a unique token from APNS or FCM
• User encrypts that token into a special transaction type (AIP-6: Signal Messages) and sends it to an ADAMANT blockchain node
• Meanwhile, the ANS polls the ADAMANT node continuously to find Signal Messages. After it saves the token (alongside the ADM address) or updates the old one into a local DB
• ANS polls the ADAMANT node and filters transactions where the user is the recipient. ANS asks APNS/FCM to deliver these transactions to the user's device
• APNS or FCM notifies the user's device
• The user's device receives a notification and decrypts the transaction using a private key

sequenceDiagram
    participant UserDevice as User's Device
    participant APNS_FCM as APNS/FCM
    participant ANS as ADAMANT Notification Service (ANS)
    participant ADAMANT as ADAMANT Node

    UserDevice->>APNS_FCM: Request unique token
    APNS_FCM-->>UserDevice: Return unique token
    UserDevice->>UserDevice: Encrypt token into special transaction (AIP-6)
    UserDevice->>ADAMANT: Send encrypted token to ADAMANT node

    loop Continuously
        ANS->>ADAMANT: Poll for Signal Messages
        ADAMANT-->>ANS: Return Signal Messages
        ANS->>ANS: Save or update token in local DB
    end

    loop Continuously
        ANS->>ADAMANT: Poll for transactions where user is recipient
        ADAMANT-->>ANS: Return transactions with encrypted messages
        ANS->>APNS_FCM: Ask to deliver transaction to user's device using token
    end

    APNS_FCM-->>UserDevice: Notify user's device
    UserDevice->>UserDevice: Decrypt transaction using private key

Loading

ANS

To register a token you must sign and send a signal transaction (AIP-6: Signal Messages) to an ADAMANT node. You must set the recipientId of the current ANS service so the service can decode the transaction.

Payload format:

type SignalMessagePayload = {
  token: string;
  provider: "APNS" | "FCM";
  action: "add" | "remove";
}

• token: User's device token
• provider: Push service provider
  • APNS: Apple Push Notification service (for iOS app)
  • FCM: Firebase Cloud Messaging (for Web/Android apps)
• action: Signal action
  • add: Register new devise
  • remove: Unregister device

Register new device

The service will save the token to the database and start monitoring new messages on the blockchain. As soon as a new message arrives, a push notification will be sent.

{
  "token": "DeviceToken",
  "provider": "FCM",
  "action": "add"
}

Unregister device

The service will remove the device token from the database and stop sending push notifications.

{
  "token": "DeviceToken",
  "provider": "FCM",
  "action": "remove"
}