Skip to main content

Link Ronin Waypoint to your existing account system

Overview​

If your project 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​

MethodDescriptionUse case
Wallet providerAppend the user's keyless (or EOA) wallet address to the list of user's wallets in your system.Use this method if you just need the wallet address for making in-game transactions.
Identity providerAppend the unique ID associated with the Ronin Waypoint account to the user's identity in your system.Use this method if you want to be able to verify the user's identity when they sign in.

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 Handle user wallets.

  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 IdP​

This section explains how to link the user ID associated with the user's Ronin Waypoint account 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 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 Handle user wallets to retrieve the wallet addresses.