Solver Relay

Solver Relay is an additional system component that optimizes frontends←→solvers quoting, and intent discovery process. Any frontend app may use a generic foundation-hosted Solver Relay or launch its own instance to customize preferred solver accounts.

Defuse protocol may operate without a Solver Relay component:

frontends may use any other quoting mechanisms to compose an intent for the end user
solvers may index Near the blockchain to find intents to fill.

However, using Solver Relay is recommended for speed optimization goals.

OpenAPI Specification

Frontend JSON-RPC Endpoint

POST: https://solver-relay-v2.chaindefuser.com/rpc

1. Quote asset prices from solvers

Allow the front end to estimate potential output for a given exact input or the required input for a given exact output based on user intent. The solver relay will forward a quote request to all connected solvers, wait for up to 1200 ms, and return all available quote options to the user. Only one of exact_amount_in or exact_amount_out should be provided in the request, not both.

Parameters

defuse_asset_identifier_in - asset to trade from
defuse_asset_identifier_out- asset to trade to
exact_amount_in- amount of token_in for exchange
exact_amount_out- amount of token_out for exchange
quote_id(optional) - An additional identifier for the quote. This is particularly useful when also listening for quotes
min_deadline_ms(optional) - minimum validity time for an offer from solvers. The shorter the time, the better the price solvers can offer.

Response

quotes[]
- quote_hash- quote identifier
- defuse_asset_identifier_in - asset to trade from
- defuse_asset_identifier_out - asset to trade to
- amount_in:
  - If exact_amount_in is defined: Specifies token_in amount for the exchange.
  - If exact_amount_in is not defined: Represents a proposed amount of token_in.
- amount_out:
  - If exact_amount_out is defined: Specifies token_out amount for the exchange.
  - If exact_amount_out is not defined: Represents a proposed amount of token_out.
- expiration_time - expiration date of the offer from the solver

Example

// Request
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "quote",
    "params":  [
        {
            "defuse_asset_identifier_in": "nep141:ft1.near",
            "defuse_asset_identifier_out": "nep141:ft2.near",
            "exact_amount_in": "1000", 
            "quote_id": "00000000-0000-0000-0000-000000000000", // OPTIONAL. default will be generated randomly
            "min_deadline_ms": "60000" // OPTIONAL. default 120_000ms / 2min
        }
    ]
}


// Response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "quotes":[
            {
                "quote_hash": "00000000000000000000000000000000",
                "defuse_asset_identifier_in": "nep141:ft1.near",
                "defuse_asset_identifier_out": "nep141:ft2.near",
                "amount_in": "1000", 
                "amount_out": "2000"
                "expiration_time": "1727784627" //UNIX TIMESTAMP
            }, 
            // ...
        ]
    }
}

2. Publish intent

If the user is satisfied with the offer provided by the solver, they can sign the intent and send it to the solver relay for execution. Relay supports this types of signatures for publicsh intent: nep413, erc191, raw_ed25519

Parameters(NEP413)

quote_hashes - quote hashes to execute all merged intents
signed_data - intent content with signature
- standard - content signature standard
- payload- content of the intent
  - message
    signer_id - Defuse account id
    intents[] - Intent data
    intent - Intent type
    deadline - valid until
    timestamp - in seconds
    block_number - near block number
  - nonce - unique nonce for operation
  - recipient - Defuse contract address
  - callbackUrl(optional) - needed for some wallets
- signature - signed content
- public_key - signer's public key

Parameters(ERC191)

quote_hashes - quote hashes to execute all merged intents
signed_data - intent content with signature
- standard - content signature standard
- payload - STRINGIFIED payload
  - signer_id - Defuse account id
  - intents[] - Intent data
    intent - Intent type
  - deadline - valid until
    timestamp - in seconds
    block_number - near block number
  - nonce - unique nonce for operation
  - veryfying_contract - use "intents.near"
- signature - signed content

Parameters(RAW_ED25519)

quote_hashes - quote hashes to execute all merged intents
signed_data - intent content with signature
- standard - content signature standard
- payload - STRINGIFIED payload
  - signer_id - Defuse account id
  - intents[] - Intent data
    intent - Intent type
  - deadline - valid until
    timestamp - in seconds
    block_number - near block number
  - nonce - unique nonce for operation
  - veryfying_contract- use "intents.near"
- signature - signed content
- public_key - signer's public key

TokenDiff Intent

intent - Intent type(equals token_diff)
diff - map where:
- Keys: Represent defuse_asset_identifiers of tokens.
- Values: Represent amounts for the tokens as strings.
  - Positive values indicate tokens to be received by the account.
  - Negative values (prefixed with "-") indicate tokens to be transferred from the account.

Response

status - intent receiving status
reason - error reason (if the status is FAILED)
intent_hash - intent identifier

Example

// Request
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "publish_intent",
  "params": [
    {
      "quote_hashes": ["00000000000000000000000000000000", ...],
      "signed_data": {
        "standard": "nep413",
        "message": {
          "signer_id": "user.near",
          "deadline": {
            "timestamp": 1728910420,
            "block_number": 18446744073709551615
          },
          "intents": [
            {
              "intent": "token_diff",
              "diff": {
                "nep141:ft1.near": "300",
                "nep141:ft2.near": "-500"
              }
            },
            {
              "intent": "mt_batch_transfer",
              "receiver_id": "referral.near",
              "token_id_amounts": {
                "nep141:ft1.near": "1"
              }
            },
            {
              "intent": "ft_withdraw",
              "token": "ft1.near",
              "receiver_id": "omni-bridge.near",
              "amount": "299",
              "msg": "{\"chain_id\": 1, \"withdraw_to\": \"0x123\"}" // omni-bridge args
            }
          ]
        },
        "nonce": "87878609949187467518642340675777309892619814715982488116035839611029208327842",
        "recipient": "defuse.near",
        "signature": "ZuVBFXIGfndYn7pNyz+dhfNgsVoUqnGiNSBL6knztPsAc5REjbr5PrrDKdGlA7akg97U8RNtg0nDparXxI9+Dg==",
        "public_key": "7RuVD5I4g/cYwpGQt5zb2FEPaiGBU3WfZZkgvbcRN5M="
      }
    }
  ]
}

// Response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result":
    {
        "status": "OK", // OR FAILED
        "reason": "expired", // expired | internal | etc
        "intent_hash": "00000000000000000000000000000000"
    }
}

3. Get intent status

Check the status of the intent execution.

Parameters

intent_hash - Intent identifier

Response

intent_hash - Intent identifier
status - Intent status
data - intent additional data
- hash - transaction hash (if exists)

Statuses

PENDING - the relay successfully received a signed intent
TX_BROADCASTED - transactions have been successfully sent to be added to the block
SETTLED - Intent executed successfully
NOT_FOUND_OR_NOT_VALID_ANYMORE - Intent not found or no valid anymore

Example

// Request
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_status",
    "params":  [
        {
            "intent_hash": "00000000000000000000000000000000"
        }
    ]
}

// Response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "intent_hash": "00000000000000000000000000000000"
        "status": "SETTLED",
        "data": {
            "hash": "0x..." // if exists
        }
    }
}

Solver WS Endpoint

wss://solver-relay-v2.chaindefuser.com/ws

1. Subscribe to quote/quote_status requests

Parameters

method - subscribe
params[0] - subscription name ("quote","quote_status")

Response

result - subscription identifier which can be used to track following events

Example

// Request
{
    "jsonrpc": "2.0", 
    "id": 1, 
    "method": "subscribe", 
    "params": ["quote"]
}

// Response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "00000000-0000-0000-0000-000000000000", // subscriptionId
}

defuse_asset_identifier_out - asset to trade to

2. Receive quote requests

Event data

subscription - subscription identifier
quote_id - quote identifier
defuse_asset_identifier_in - asset to trade from
exact_amount_in- amount of token_in for exchange
exact_amount_out- amount of token_out for exchange
- Condition: Only one of exact_amount_in orexact_amount_out can will be specified in a request.
min_deadline_ms - minimum validity time for an offer from solvers. The shorter the time, the better the price solvers can offer.

Example

// Event
{
    "jsonrpc": "2.0"
    "method": "subscribe",
    "params": {
        "subscription": "00000000-0000-0000-0000-000000000000",
        "quote_id":"00000000-0000-0000-0000-000000000000",
        "defuse_asset_identifier_in": "nep141:ft1.near",
        "defuse_asset_identifier_out": "nep141:ft2.near",
        "exact_amount_in": "1000", 
        "min_deadline_ms": "60000" // OPTIONAL. default 120_000ms / 2min
    }
}

3. Respond to quote requests

Parameters

quote_id - user's quote identifier
quote_output - quote result
- amount_out - proposed amountfor exact_amount_in requests
- amount_in - proposed amountfor exact_amount_out requests
signed_data - intent content with signature
- standard - content signature standard
- payload- content of the intent
  - message
    signer_id - Defuse account id
    intents[] - Intent data
    intent - Intent type
    deadline - valid until
    timestamp - in seconds
    block_number - near block number
  - nonce - unique nonce for operation
  - recipient - Defuse contract address
- signature - signed content
- public_key - signer's public key
other_quote_hashes - hashes of other quote results to fulfill the current intent

Response

result - proposal receipt status

Example

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "quote_response",
  "params": [
    {
      "quote_id":"00000000-0000-0000-0000-000000000000",
      "quote_output": {
        "amount_out": "300",
      },
      "signed_data": {
        "standard": "nep413",
        "message": {
          "signer_id": "solver.near",
          "deadline": {
            "timestamp": 1728910420,
            "block_number": 18446744073709551615
          },
          "intents": [
            {
              "intent": "token_diff",
              "diff": {
                "nep141:ft2.near": "-300",
                "nep141:ft1.near": "500"
              }
            },
          ]
        },
        "nonce": "87878609949187467518642340675777309892619814715982488116035839611029208327842",
        "recipient": "defuse.near",
        "signature": "ZuVBFXIGfndYn7pNyz+dhfNgsVoUqnGiNSBL6knztPsAc5REjbr5PrrDKdGlA7akg97U8RNtg0nDparXxI9+Dg==",
        "public_key": "7RuVD5I4g/cYwpGQt5zb2FEPaiGBU3WfZZkgvbcRN5M="
      }
    },
    "other_quote_hashes": ["00000000000000000000000000000000", ...] //optional
  ]
}

// Response
{
    "jsonrpc": "2.0", 
    "id": 1, 
    "result": "OK", 
}

4.Receive quote_status event

Event data

quote_hash - solver intent hash used to identify quote
intent_hash - user intent hash(identifier)
tx_hash - hash of mined intent

Example

// Event
{
    "jsonrpc": "2.0"
    "method": "subscribe",
    "params": {
        "quote_hash": "00000000000000000000000000000000",
        "intent_hash":"00000000000000000000000000000000",
        "tx_hash": "00000..."
    }
}

5. Unsubscribe

Parameters

method - unsubscribe
params[0] - subscription identifier

Example

// Request
{
    "jsonrpc": "2.0", 
    "id": 1, 
    "method": "unsubscribe", 
    "params": ["00000000-0000-0000-0000-000000000000"] //subscriptionId
}

// Response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "OK"
}

PreviousIntroduction NextSolvers

Last updated 1 month ago

// Request { "id": 1, "jsonrpc": "2.0", "method": "quote", "params": [ { "defuse_asset_identifier_in": "nep141:ft1.near", "defuse_asset_identifier_out": "nep141:ft2.near", "exact_amount_in": "1000", "quote_id": "00000000-0000-0000-0000-000000000000", // OPTIONAL. default will be generated randomly "min_deadline_ms": "60000" // OPTIONAL. default 120_000ms / 2min } ] } // Response { "jsonrpc": "2.0", "id": 1, "result": { "quotes":[ { "quote_hash": "00000000000000000000000000000000", "defuse_asset_identifier_in": "nep141:ft1.near", "defuse_asset_identifier_out": "nep141:ft2.near", "amount_in": "1000", "amount_out": "2000" "expiration_time": "1727784627" //UNIX TIMESTAMP }, // ... ] } }

// Request { "id": 1, "jsonrpc": "2.0", "method": "publish_intent", "params": [ { "quote_hashes": ["00000000000000000000000000000000", ...], "signed_data": { "standard": "nep413", "message": { "signer_id": "user.near", "deadline": { "timestamp": 1728910420, "block_number": 18446744073709551615 }, "intents": [ { "intent": "token_diff", "diff": { "nep141:ft1.near": "300", "nep141:ft2.near": "-500" } }, { "intent": "mt_batch_transfer", "receiver_id": "referral.near", "token_id_amounts": { "nep141:ft1.near": "1" } }, { "intent": "ft_withdraw", "token": "ft1.near", "receiver_id": "omni-bridge.near", "amount": "299", "msg": "{\"chain_id\": 1, \"withdraw_to\": \"0x123\"}" // omni-bridge args } ] }, "nonce": "87878609949187467518642340675777309892619814715982488116035839611029208327842", "recipient": "defuse.near", "signature": "ZuVBFXIGfndYn7pNyz+dhfNgsVoUqnGiNSBL6knztPsAc5REjbr5PrrDKdGlA7akg97U8RNtg0nDparXxI9+Dg==", "public_key": "7RuVD5I4g/cYwpGQt5zb2FEPaiGBU3WfZZkgvbcRN5M=" } } ] } // Response { "jsonrpc": "2.0", "id": 1, "result": { "status": "OK", // OR FAILED "reason": "expired", // expired | internal | etc "intent_hash": "00000000000000000000000000000000" } }

// Request { "id": 1, "jsonrpc": "2.0", "method": "get_status", "params": [ { "intent_hash": "00000000000000000000000000000000" } ] } // Response { "jsonrpc": "2.0", "id": 1, "result": { "intent_hash": "00000000000000000000000000000000" "status": "SETTLED", "data": { "hash": "0x..." // if exists } } }

// Request { "jsonrpc": "2.0", "id": 1, "method": "subscribe", "params": ["quote"] } // Response { "jsonrpc": "2.0", "id": 1, "result": "00000000-0000-0000-0000-000000000000", // subscriptionId }

// Event { "jsonrpc": "2.0" "method": "subscribe", "params": { "subscription": "00000000-0000-0000-0000-000000000000", "quote_id":"00000000-0000-0000-0000-000000000000", "defuse_asset_identifier_in": "nep141:ft1.near", "defuse_asset_identifier_out": "nep141:ft2.near", "exact_amount_in": "1000", "min_deadline_ms": "60000" // OPTIONAL. default 120_000ms / 2min } }

// Request { "jsonrpc": "2.0", "id": 1, "method": "quote_response", "params": [ { "quote_id":"00000000-0000-0000-0000-000000000000", "quote_output": { "amount_out": "300", }, "signed_data": { "standard": "nep413", "message": { "signer_id": "solver.near", "deadline": { "timestamp": 1728910420, "block_number": 18446744073709551615 }, "intents": [ { "intent": "token_diff", "diff": { "nep141:ft2.near": "-300", "nep141:ft1.near": "500" } }, ] }, "nonce": "87878609949187467518642340675777309892619814715982488116035839611029208327842", "recipient": "defuse.near", "signature": "ZuVBFXIGfndYn7pNyz+dhfNgsVoUqnGiNSBL6knztPsAc5REjbr5PrrDKdGlA7akg97U8RNtg0nDparXxI9+Dg==", "public_key": "7RuVD5I4g/cYwpGQt5zb2FEPaiGBU3WfZZkgvbcRN5M=" } }, "other_quote_hashes": ["00000000000000000000000000000000", ...] //optional ] } // Response { "jsonrpc": "2.0", "id": 1, "result": "OK", }

// Event { "jsonrpc": "2.0" "method": "subscribe", "params": { "quote_hash": "00000000000000000000000000000000", "intent_hash":"00000000000000000000000000000000", "tx_hash": "00000..." } }

// Request { "jsonrpc": "2.0", "id": 1, "method": "unsubscribe", "params": ["00000000-0000-0000-0000-000000000000"] //subscriptionId } // Response { "jsonrpc": "2.0", "id": 1, "result": "OK" }