Ronin Waypoint iOS SDK

Overview

The Ronin Waypoint iOS SDK lets developers integrate the account and wallet features of the Ronin Waypoint service into iOS apps developed with Swift. After the integration, users can sign in to your game with their Ronin Waypoint account and connect their keyless wallet for instant in-game transactions.

GitHub repository: skymavis/waypoint-iOS.

Usage

All functions of the SDK return a string in the format of the deep link schema that you registered in the Developer Console. For example, mydapp://callback.
To parse deep links returned by the SDK, use the Deep link parser utility or implement your own parser.

Features

Authorize users: let users sign in to your app with Ronin Waypoint to connect their keyless wallet and an optional EOA wallet.
Send transactions: transfer RON, ERC-20 tokens, and make contract calls for in-game transactions.
Sign messages and typed data: prove ownership of a wallet or sign structured data.

Prerequisites

iOS 13.0 or later and Xcode 15.4 or later.
An app created in the Developer Console.
Permission to use the Sky Mavis Account service. Request in the Developer Console under your app > App Permission > Sky Mavis Account (OAuth 2.0) > Request Access.
A client ID that you can find in the Developer Console under Products > Waypoint Service > CLIENT ID (APPLICATION ID).
A redirect URI registered in the Developer Console under Products > Waypoint Service > REDIRECT URI.

For more information about the initial setup, see Get started.

Steps

Step 1. Install the SDK

Swift Package Manager
CocoaPods

In Xcode, select your target, then go to General > + > Add Other > Add Package Dependency.
Enter the following GitHub repository URL: https://github.com/skymavis/waypoint-iOS.

In your Podfile, add the following line:
```
pod 'SkyMavis-Waypoint', '0.1.3'
```
Run the following command:
```
pod install
```

Step 2. Initialize the SDK

Initialize the client:

// Import the SDK
import waypoint

// Testnet configuration
let waypoint = Waypoint(
    waypointOrigin: "https://waypoint.roninchain.com",
    clientId: "{YOUR_CLIENT_ID}",
    chainRpc: "https://saigon-testnet.roninchain.com/rpc",
    chainId: 2021
)

Parameters:

waypointOrigin: the base URL of Ronin Waypoint for all API calls. Use https://waypoint.roninchain.com for production and https://id.skymavis.one for staging.
clientId: the client ID registered in the Developer Console.
chainRpc: the RPC endpoint through which you want to connect to Ronin. The example uses a public endpoint for the Saigon testnet: https://saigon-testnet.roninchain.com/rpc. For more information, see RPC endpoints.
chainId: the ID of the Ronin chain you want to connect to. Use 2021 for the Saigon testnet and 2020 for the Ronin mainnet.

Step 3. Authorize a user

Initializes the authorization process, allowing a user to sign in or sign up for a Ronin Waypoint account, and connect their wallet. Returns an authorization response containing an ID token and the user's keyless wallet address.

func authorize(from viewController: UIViewController, state: String, redirect: String) async -> String

Parameters:

from: the UIViewController of your app.
state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
redirect: the redirect URI registered in the Developer Console.

Example:

// Implement the action for authorization
@objc func authorizeTapped() -> Void {
    // Generate a random state using the SDK utility
    let state = Utils.generateRandomState()
    // Example: "mydapp://callback"
    let redirect = "${YOUR_DEEPLINK_REDIRECT}"
    Task {
        let result = await waypoint.authorize(from: self, state: state, redirect: redirect)
        // Optionally, parse the result using this utility
        let response = Utils.parseDeepLink(deeplink: result)
    }
}

Step 4. Validate the ID token

After receiving the ID token from the authorization response, validate it and issue an access token to allow access to your server's resources. For more information, see Validate ID token.

Step 5. Interact with the wallet

Transfer the native token

Transfers RON tokens to a recipient's address, returning a transaction response containing the transaction hash.

func sendTransaction(from viewController: UIViewController, state: String, redirect: String, to: String, value: String) async -> String

Parameters:

from: the UIViewController of your app.
state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
redirect: the redirect URI registered in the Developer Console.
to: the recipient address.
value: the amount of RON to send, specified in wei (1 RON = 10^18 wei).

Example: transfer 0.1 RON to the recipient address.

@objc func sendTransactionTapped() -> Void {
    // Generate a random state using the SDK utility
    let state = Utils.generateRandomState()
    // Recipient address
    let to = "${YOUR_RECEIVER_ADDRESS}"
    // 0.1 RON in wei
    let value = "100000000000000000"
    // Example: "mydapp://callback"
    let redirect = "${YOUR_DEEPLINK_REDIRECT}"
    Task {
        // Send the transaction after initializing the SDK
        let result = await waypoint.sendTransaction(from: self, state: state, redirect: redirect, to: to, value: value)
        // Optionally, parse the result using this utility
        let response = Utils.parseDeepLink(deeplink: result)
    }
}

Sign a message

Signs a plain text message, returning a transaction response containing the signature.

public func personalsign(from viewcontroller: uiviewcontroller, state: string, redirect: string, message: string) async -> string

Parameters:

from: the UIViewController of your app.
state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
redirect: the redirect URI registered in the Developer Console.
message: the message to sign.

Example: sign the message accepting the terms and conditions.

@objc func personalSignTapped() -> Void {
    // Generate a random state using the SDK utility
    let state = Utils.generateRandomState()
    // Message to sign
    var message = "I agree to the terms and conditions."
    // Example: "mydapp://callback"
    let redirect = "${YOUR_DEEPLINK_REDIRECT}"
    Task {
        // Sign the message after initializing the SDK
        let result = await waypoint.personalSign(from: self, state: state, redirect: redirect, message: message)
        // Optionally, parse the result using this utility
        let response = Utils.parseDeepLink(deeplink: result)

    }
}

Sign typed data

Signs typed data structured according to the EIP-712 standard, returning a transaction response containing the signature.

func signTypedData(from viewController: UIViewController, state: String, redirect: String, typedData: String) async -> String

Parameters:

from: the UIViewController of your app.
state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
redirect: the redirect URI registered in the Developer Console.
typedData: a JSON string that specifies the EIP-712 typed structured data to be signed by the user.

Example: sign typed data for an order on Axie Marketplace.

@objc func signTypedDataTapped() -> Void {
    // Typed data to sign
    let typedData = """
    {
        "types": {
            "Asset": [
                {"name": "erc", "type": "uint8"},
                {"name": "addr", "type": "address"},
                {"name": "id", "type": "uint256"},
                {"name": "quantity", "type": "uint256"}
            ],
            "Order": [
                {"name": "maker", "type": "address"},
                {"name": "kind", "type": "uint8"},
                {"name": "assets", "type": "Asset[]"},
                {"name": "expiredAt", "type": "uint256"},
                {"name": "paymentToken", "type": "address"},
                {"name": "startedAt", "type": "uint256"},
                {"name": "basePrice", "type": "uint256"},
                {"name": "endedAt", "type": "uint256"},
                {"name": "endedPrice", "type": "uint256"},
                {"name": "expectedState", "type": "uint256"},
                {"name": "nonce", "type": "uint256"},
                {"name": "marketFeePercentage", "type": "uint256"}
            ],
            "EIP712Domain": [
                {"name": "name", "type": "string"},
                {"name": "version", "type": "string"},
                {"name": "chainId", "type": "uint256"},
                {"name": "verifyingContract", "type": "address"}
            ]
        },
        "domain": {
            "name": "MarketGateway",
            "version": "1",
            "chainId": 2021,
            "verifyingContract": "0xfff9ce5f71ca6178d3beecedb61e7eff1602950e"
        },
        "primaryType": "Order",
        "message": {
            "maker": "0xd761024b4ef3336becd6e802884d0b986c29b35a",
            "kind": "1",
            "assets": [
                {
                    "erc": "1",
                    "addr": "0x32950db2a7164ae833121501c797d79e7b79d74c",
                    "id": "2730069",
                    "quantity": "0"
                }
            ],
            "expiredAt": "1721709637",
            "paymentToken": "0xc99a6a985ed2cac1ef41640596c5a5f9f4e19ef5",
            "startedAt": "1705984837",
            "basePrice": "500000000000000000",
            "endedAt": "0",
            "endedPrice": "0",
            "expectedState": "0",
            "nonce": "0",
            "marketFeePercentage": "425"
        }
    }
    """
    // Generate a random state using the SDK utility
    let state = Utils.generateRandomState()
    // Example: "mydapp://callback"
    let redirect = "${YOUR_DEEPLINK_REDIRECT}"
    Task {
        // Sign the typed data after initializing the SDK
        let result = await waypoint.signTypedData(from: self, state: state, redirect: redirect, typedData: typedData)
        // Optionally, parse the result using this utility
        let response = Utils.parseDeepLink(deeplink: result)
    }
    }

Call a contract

Executes a custom transaction on a smart contract, returning a transaction response containing the transaction hash.

func callContract(from viewController: UIViewController, state: String, redirect: String, contractAddress: String, data: String, value: String? = nil) async -> String

Parameters:

from: the UIViewController of your app.
state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
redirect: the redirect URI registered in the Developer Console.
contractAddress: the address of the smart contract on which to execute the transaction.
data: the transaction data to send to the smart contract, encoded as a hex string.
value: the amount of RON in wei (1 RON = 10^18 wei) to send along with the transaction. For non-payable smart contracts, the value is 0x0.

Example: allow another contract to spend 1 AXS on user's behalf.

@objc func callContractTapped() -> Void {
    // Contract address
    let contractAddress = "0x3c4e17b9056272ce1b49f6900d8cfd6171a1869d"
    // Data for approving 1 AXS
    let data = "0xa9059cbb000000000000000000000000edb40e7abaa613a0b06d86260dd55c7eb2df2447000000000000000000000000000000000000000000000000016345785d8a0000"
    // Generate a random state using the SDK utility
    let state = Utils.generateRandomState()
    Task {
        // Call the contract after initializing the SDK
        let result = await waypoint.callContract(from: self, state: state, redirect: redirect, contractAddress: contractAddress, data: data)
        // Optionally, parse the result using this utility
        let response = Utils.parseDeepLink(deeplink: result)
    }
}

Utilities

Random state generator

Use the generateRandomState utility to generate a random state for requests.

static func generateRandomState() -> String

Deep link parser

Use the parseDeepLink function to parse a deep link returned by a function, returning a Response object.

static func parseDeepLink(deeplink: String) -> Response

Response object

The Response class stores the parsed response parameters. The object returned from the parseDeepLink function contains information about the response, including whether the operation was successful, the method called, and additional details such as the user's keyless wallet address, data like transaction hashes, and state.

public class Response {
    private var success: Bool?
    private var method: String?
    private var data: String?
    private var address: String?
    private var state: String?
}

Reference

Response types

Authorization response

Ronin Waypoint returns an authorization response after a user connects their wallet to your app.

Successful authorization

mydapp://callback?state=05d805a4-1633-4ad3-bfb2-dc9a4dccdd7c&method=auth&version=1.4&type=success&data=ey...address=0x3C...77

Response parameters:

state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
method: the method used for the request (auth).
version: the version of the Ronin Waypoint service.
type: the response type (success).
data: the ID token that contains encoded user information.
address: the user's keyless wallet address.

Authorization error

mydapp://callback?state=05d805a4-1633-4ad3-bfb2-dc9a4dccdd7c&method=auth&version=1.4&type=fail&code=1000&message=%5BWALLET_USER_CANCEL%5D+User+rejected

Response parameters:

type: the response type (fail).
code: the error code.
message: a message describing the error.

Transaction response

Ronin Waypoint returns a transaction response after a user sends a transaction, signs a message, signs typed data, or calls a contract on the blockchain.

Successful transaction

mydapp://callback?state=05d805a4-1633-4ad3-bfb2-dc9a4dccdd7c&method=send&version=1.4&type=success&data=0x69...ac

Response parameters:

state: a unique random identifier used to manage requests from the client to Ronin Waypoint.
method: the method used for the request (send for transactions and sign for signing).
version: the version of the Ronin Waypoint service.
type: the response type (success).
data: the transaction hash.

Transaction error

mydapp://callback?state=05d805a4-1633-4ad3-bfb2-dc9a4dccdd7c&method=send&version=1.4&type=fail&code=1000&message=%5BTRANSACTION_REJECTED%5D+Transaction+rejected

Response parameters:

type: the response type (fail).
code: the error code.
message: a message describing the error.

FAQ

Where can I find the client ID?

To find your app's client ID, open the Developer Console, then click Waypoint Service, and then in the Client credentials section, locate the CLIENT ID (APPLICATION ID) field.

Where can I find the chain ID?

The chain ID is 2020 for the Ronin mainnet and 2021 for the Saigon testnet.

Was this helpful?

Happy React is loading...

Overview​

Usage​

Features​

Prerequisites​

Steps​

Step 1. Install the SDK​

Step 2. Initialize the SDK​

Step 3. Authorize a user​

Step 4. Validate the ID token​

Step 5. Interact with the wallet​

Transfer the native token​

Sign a message​

Sign typed data​

Call a contract​

Utilities​

Random state generator​

Deep link parser​

Response object​

Reference​

Response types​

Authorization response​

Successful authorization​

Authorization error​

Transaction response​

Successful transaction​

Transaction error​

FAQ​

Where can I find the client ID?​

Where can I find the chain ID?​

Overview

Usage

Features

Prerequisites

Steps

Step 1. Install the SDK

Step 2. Initialize the SDK

Step 3. Authorize a user

Step 4. Validate the ID token

Step 5. Interact with the wallet

Transfer the native token

Sign a message

Sign typed data

Call a contract

Utilities

Random state generator

Deep link parser

Response object

Reference

Response types

Authorization response

Successful authorization

Authorization error

Transaction response

Successful transaction

Transaction error

FAQ

Where can I find the client ID?

Where can I find the chain ID?