Link Ronin Waypoint to your existing account service

Overview

If your game already has an account system, there are two ways you can link Ronin Waypoint to it: as a wallet provider or as an identity provider (IdP). This guide walks you through the steps for implementing both methods.

Use cases

Method	Use case
Wallet provider	Treat Ronin Waypoint as only a payment method for in-game purchases. Your game can use the keyless wallet without having to go through the Sky Mavis Account authorization to make Web3 transactions.
Identity provider	Link the Ronin Waypoint user ID to your existing account system. Your game can use Ronin Waypoint as another identity provider for the existing system.

Use Ronin Waypoint as a wallet provider

This section guides you through linking a user's wallet address to their account in your system.

Process flow

Implementation steps

Example database schema

Here's an example of how you might structure your database to store user wallets:

create users (
  id text primary key,
  email text,
  created_at timestamp,
  updated_at timestamp
)

create user_wallets (
  id text primary key,
  user_id int references users(id),
  address string,
  kind string
)

In this example, id is a text field, but in practice, it can be an integer, UUID, or any other unique identifier.

Example data fixture

Here's an example of what the user data might look like in JSON format:

users = [
  { 
    "id": "user-1",
    "email": "a@gmail.com",
    "created_at": "2024-08-30 12:00",
    "updated_at": "2024-08-30 12:00",
    "wallets": [
      {
        "id": "user-1-wallet-1",
        "address": "0xaaa...",
        "kind": "ronin"
      },
      {
        "id": "user-1-wallet-2",
        "address": "0xbbb...",
        "kind": "keyless"
      }
    ]
  },
  { 
    "id": "user-2",
    "email": "b@gmail.com",
    "created_at": "2024-08-30 12:00",
    "updated_at": "2024-08-30 12:00",
    "wallets": [
      {
        "id": "user-2-wallet-1",
        "address": "0xccc...",
        "kind": "ronin"
      }
    ]
  },
]

Let's link user-2's keyless wallet to their account in your system. Follow these steps:

1. Authorize the user: use Ronin Waypoint to authorize the user and receive an ID token. For more information, see Ronin Waypoint Unity SDK.

2. Submit ID token: have the user send this token to your backend server with their own credentials (such as their access token). For example:

   curl -X POST https://account.example.com/users/link-to-waypoint-wallet \
     -H 'Authorization: Bearer {user_access_token}' \
     --data-binary @- << EOF
   {
       "id_token": "{ronin_waypoint_id_token}"
   }
   EOF

3. Verify ID token: on your server, verify the ID token submitted by the user. For more information, see Validate ID token.

4. Update the database: take the wallet address associated with this user (through the UUID in the sub field in the ID token) and update the user's wallet in your database.

   • account.wallet.identity: the keyless wallet address bound to the user's identity. This wallet address is immutable and can't be changed by the user.
   • account.wallet.secondary: the EOA wallet address linked by the user on the account management page. This address can be changed by the user, so plan your implementation accordingly.

   For more details on handling these two wallet types, see Get user profile.

5. Append user's wallet address: add the wallet address to the list of wallets associated with this user in your database:

   // Example JSON array for demonstration
   // Not a valid SQL query
   
   users[2].wallets.append({
     "id": "user-2-wallet-2",
     "kind": "keyless",
     "address": "{account.wallet.identity}"  
   })
   
   users[2].wallets.append({
     "id": "user-2-wallet-3",
     "kind": "ronin",
     "address": "{account.wallet.secondary}"  
   })

Use Ronin Waypoint as an identity provider

This section explains how to link the user ID associated with the user's Ronin Waypoint account to their existing account in your system.

Process flow

Implementation steps

Example database schema

Here's an example of how you might structure your database to store user accounts:

create users (
  id text primary key,
  email text,
  created_at timestamp,
  updated_at timestamp
)

create accounts (
  id text,
  user_id text references users(id),
  provider string,
  kind string,
  primary key(id, provider)
)

In this example, id is a text field, but in practice, it can be an integer, UUID, or any other unique identifier.

Example data fixture

Here's an example of what the user data might look like in JSON format:

users = [
  {
    "id": "user-1",
    "email": "a@gmail.com",
    "created_at": "2024-08-30 12:00",
    "updated_at": "2024-08-30 12:00",
    "accounts": [
      {
        "id": "123",
        "provider": "google",
        "kind": "social"
      },
      {
        "id": "0xaaa...",
        "provider": "metamask",
        "kind": "wallet"
      }
    ]
  },
  {
    "id": "user-2",
    "email": "b@gmail.com",
    "created_at": "2024-08-30 12:00",
    "updated_at": "2024-08-30 12:00",
    "accounts": [
      {
        "id": "456",
        "address": "google",
        "kind": "social"
      }
    ]
  },
]

Let's link the user ID of the Ronin Waypoint account user-2 to their account in your system. Follow these steps:

1. Authorize the user: use Ronin Waypoint to authorize the user and receive an ID token. For more information, see Ronin Waypoint Unity SDK.

2. Submit ID token: have the user submit the ID token to your backend server with their own credentials (such as their access token). For example:

   curl -X POST https://account.example.com/users/link-to-waypoint-account \
     -H 'Authorization: Bearer {user_access_token}' \
     --data-binary @- << EOF
   {
       "id_token": "{ronin_waypoint_id_token}"
   }
   EOF

3. Verify ID token: on your server, verify the ID token submitted by the user. For more information, see Validate ID token.

4. Update the database and append the account: take the UUID (sub in the ID token) and append the value to the list of accounts associated with this user in your database:

   // Example JSON array for demonstration
   // Not a valid SQL query
   
   users[2].accounts.append({
     "id": "{sub in the ID token}",
     "provider": "waypoint",
     "kind": "social",
   })

5. Access wallet information: to access the user's wallets, follow the steps in Get user profile.