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.
- 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.
GitHub repository: skymavis/waypoint-iOS.
Features
- Authorize users: let users sign in to your app with Ronin Waypoint and connect their 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.
Example app
The iOS SDK includes an example app that demonstrates the SDK features. To run the example app, clone the skymavis/waypoint-ios repository, then open the project in Xcode.
Make sure to fill in the client ID and redirect URI that you registered in the Developer Console.
Setup
Installation
- 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
Initialization
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. Usehttps://waypoint.roninchain.com
for production andhttps://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. Use2021
for the Saigon testnet and2020
for the Ronin mainnet.
Usage
User authorization and wallet connection
Use the authorize
function to sign the user up or log in with the Ronin Waypoint service and connect the user's wallet. The function opens the Ronin Waypoint login page. After the user authenticates, Ronin Waypoint redirects back to your app and returns an ID token and the user's wallet addresses, which includes the keyless wallet address and optional EOA (externally owned account) wallet address, if the user connected one on the account management site. For more information about the response format, see authorization response.
func authorize(from viewController: UIViewController, state: String, redirect: String) async -> String
Parameters:
from
: theUIViewController
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)
}
}
Wallet interactions
RON transfer
Use the sendTransaction
function to send RON tokens to a recipient's address. The function returns a transaction response containing the transaction hash.
func sendTransaction(from viewController: UIViewController, state: String, redirect: String, to: String, value: String) async -> String
Parameters:
from
: theUIViewController
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 another 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)
}
}
Message signing
Use the signMessage
function to sign plain text messages with the user's wallet. The function returns a transaction response containing the signature.
public func personalsign(from viewcontroller: uiviewcontroller, state: string, redirect: string, message: string) async -> string
Parameters:
from
: theUIViewController
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)
}
}
Typed data signing
Use the signTypedData
function to sign 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
: theUIViewController
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)
}
}
Contract function calls
Use the callContract
function to execute a function 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
: theUIViewController
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 is0x0
.
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 wallet addresses, 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 secondaryAddress: String?
private var state: String?
}
Reference
Function summary
Function | Description | Use case |
---|---|---|
authorize | Signs user in to Ronin Waypoint and returns their wallet address. | Used for user sign-in and wallet connection. |
sendTransaction | Sends RON tokens to a recipient address. | Supports in-game purchases or token transfers. |
signMessage | Signs plain text messages with the user's wallet. | Proves wallet ownership or agreement to terms. |
signTypedData | Signs structured data following the EIP-712 standard. | Useful for complex data structures, such as marketplace orders. |
callContract | Executes functions on smart contracts. | Supports in-game ERC-20 token transfers, approvals, and other contract interactions. |
Response types
Authorization response
Ronin Waypoint returns an authorization response after a user connects their wallet to your app.
Authorization success
mydapp://callback?state=05d805a4-1633-4ad3-bfb2-dc9a4dccdd7c&method=auth&version=1.4&type=success&data=ey...address=0x3C...77&secondary_address=0x3f...d3
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.secondary_address
: the user's EOA wallet address, if connected.
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.
Transaction success
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 andsign
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.