Wallet Authentication
Overview of wallet authentication & Orderly keys
EIP-712
Orderly Network relies on the EIP-712 standard to authenticate wallets and accounts for critical actions, such as:
-
Account creation
-
Orderly key addition
-
Withdrawal requests
For these actions, wallet owners will need to sign specific messages from their wallet and pass the signature through the REST APIs to complete the action. The following sections describe the steps needed to complete these actions.
For other actions, such as calling trading-related RESTful APIs, a successful Orderly Key generation is required in order to use it via API authentication.
Domain
Orderly Network utilizes the following EIP-712 domain and types for the registration, access key, withdrawal and settle PnL processes.
Note that chainId
will be the id of the chain connected, which must be supported by Orderly Network.
Off-chain Domain
The Registration
and AddOrderlyKey
types are entirely processed off-chain, which is why the verifyingContract
is set to 0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC
.
{
"name": "Orderly",
"version": "1",
"chainId": chainId,
"verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC",
}
On-chain Domain
Any other type uses the on-chain domain. The address for the Ledger contract on the Orderly L2 chain can be looked up here.
{
"name": "Orderly",
"version": "1",
"chainId": chainId,
"verifyingContract": ledgerContractAddress,
}
Message Types
The message types are required for the EIP-712 algorithm to do a proper signing. Here is a list of all message types as JSON:
{
"EIP712Domain": [
{ "name": "name", "type": "string" },
{ "name": "version", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "verifyingContract", "type": "address" },
],
"Registration": [
{ "name": "brokerId", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "timestamp", "type": "uint64" },
{ "name": "registrationNonce", "type": "uint256" },
],
"AddOrderlyKey": [
{ "name": "brokerId", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "orderlyKey", "type": "string" },
{ "name": "scope", "type": "string" },
{ "name": "timestamp", "type": "uint64" },
{ "name": "expiration", "type": "uint64" },
],
"Withdraw": [
{ "name": "brokerId", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "receiver", "type": "address" },
{ "name": "token", "type": "string" },
{ "name": "amount", "type": "uint256" },
{ "name": "withdrawNonce", "type": "uint64" },
{ "name": "timestamp", "type": "uint64" },
],
"SettlePnl": [
{ "name": "brokerId", "type": "string" },
{ "name": "chainId", "type": "uint256" },
{ "name": "settleNonce", "type": "uint64" },
{ "name": "timestamp", "type": "uint64" },
],
"DelegateSigner": [
{ "name": "delegateContract", type: "address" },
{ "name": "brokerId", type: "string" },
{ "name": "chainId", type: "uint256" },
{ "name": "timestamp", type: "uint64" },
{ "name": "registrationNonce", type: "uint256" },
{ "name": "txHash", type: "bytes32" },
],
"DelegateAddOrderlyKey": [
{ "name": "delegateContract", type: "address" },
{ "name": "brokerId", type: "string" },
{ "name": "chainId", type: "uint256" },
{ "name": "orderlyKey", type: "string" },
{ "name": "scope", type: "string" },
{ "name": "timestamp", type: "uint64" },
{ "name": "expiration", type: "uint64" },
],
"DelegateWithdraw": [
{ "name": "delegateContract", type: "address" },
{ "name": "brokerId", type: "string" },
{ "name": "chainId", type: "uint256" },
{ "name": "receiver", type: "address"},
{ "name": "token", type: "string" },
{ "name": "amount", type: "uint256" },
{ "name": "withdrawNonce", type: "uint64" },
{ "name": "timestamp", type: "uint64" },
],
"DelegateSettlePnl": [
{ "name": "delegateContract", type: "address" },
{ "name": "brokerId", type: "string" },
{ "name": "chainId", type: "uint256" },
{ "name": "settleNonce", type: "uint64" },
{ "name": "timestamp", type: "uint64" },
],
}
Orderly key
Orderly Network uses the ed25519
elliptic curve standard for Orderly keys. Users can generate Orderly keys using any public ed25519
libraries and then be added to any account through the REST API.
An Orderly key is necessary to perform API authentication.
Orderly keys can have different scopes. A read
scope API can access all private read-only APIs, and a trading
scope can, in addition, access all order APIs (create order, batch create order, edit order, cancel order, cancel order by client_order-Id, cancel orders in bulk, batch cancel orders, batch cancel orders by client_order_id).
Orderly keys also have expirations for security reasons. The maximum allowed expiration of an Orderly key is 365 days.
Follow the following steps to add a new Orderly key on Orderly Network:
Generate an ed25519 key-pair
Any public ed25519 library can be used (such as this one).
Obtain signature from EIP-712
Sign a message from the wallet in the following format using the EIP-712 standard and obtain the signature
{
"brokerId": "woofi_dex",
"chainId": 80001,
"orderlyKey": "ed25519:HqN9uKJioHjAJZbadgQRGzq2e7huKg6foCyNY43hWbCk",
"scope": "trading",
"timestamp": 1685973094398,
"expiration": 1686081094398
}
where:
Name | Type | Required | Description |
---|---|---|---|
brokerId | string | Y | Builder ID, the valid list can be found [here] |
chainId | int | Y | Chain ID of registering chain (within those that are supported by the Network) |
orderlyKey | string | Y | ed25519 public key |
scope | string | Y | valid scopes are read , trading and asset . Multiple scopes can be sent, comma separated |
timestamp | timestamp | Y | timestamp in UNIX milliseconds |
expiration | timestamp | Y | Expiration time of the key in UNIX millisecondsMaximum allowed expiration is 365 days from add |
Add Orderly key
Send all the necessary information via Add Orderly key API.