# Rasa Instant Trading Implementation

## Implementing Instant Actions 

### For Frontends:

To enable instant actions on the frontend, users must delegate specific functions to solvers so they can perform actions on the user's behalf without requiring signatures for each request. 

Front-ends should ensure that the following functions are delegated to the respective solver addresses through the `delegateAccess()` method on the MultiAccount contract:

* `sendQuote`: **0x7f2755b2**
* `sendQuoteWithAffiliate`: **0x40f1310c**
* `requestToClosePosition`: **0x501e891f**
* `requestToCancelQuote`: **0xa8ffc7ab**
* `requestToCancelCloseRequest`: **0xa63b9363**
* `allocate`: **0x90ca796b**

The delegation should be initiated by calling delegateAccesses() on the [MultiAccount](https://docs.symm.io/contract-documentation/version-history/contracts-documentation-0.8.2/multiaccount) contract, specifying the user’s sub-account, the target (solver) address, and the function selectors that need to be delegated.

## For Solvers:

## Overview

This document outlines how to implement Instant Trading for Solvers. Instant trading involves creating sessions for users allowing solvers to open and close positions on traders' behalf without requiring signatures for each action.

Users must first delegate certain functions to the solver to manage positions on behalf of them (`sendQuote`, `sendQuoteWithAffiliate`, `requestToClosePosition`)

The frontend then prompts to authenticate the user for instant actions and generates a message to sign. This message includes the following details:

* Wallet Address (`address`): The multiaccount address to be used with instant trading.
* Nonce (`nonce`): The nonce related to the request.
* Domain (`domain`): The domain of the application.
* URI (`uri`): The specific endpoint the request is associated with (e.g., the login endpoint).
* Issued At (`issuedAt`): The timestamp when the message was created.
* Expiration Time (`expirationTime`): The time after which the signature is no longer valid.

Once the message is signed, the frontend sends this signed message along with other necessary data (such as the nonce, expiration time, and wallet address) to the solver API via a request (e.g., to the `/login` endpoint).

The solver should issue an access token which the frontend stores and includes it in the headers of future requests until the token expires. Solvers should validate the stored access token before proceeding with any API request. The expiration time can be set by the frontend and should be checked before every API call.

This section covers the API endpoints and request/response structures needed for instant trading.

### Authentication and Session Management

Before executing any trading actions, solvers must authenticate the user and manage sessions via the following endpoints.

### Nonce Retrieval

**Endpoint**: `GET /nonce/{activeAddress}`

* Description: Retrieve a nonce for signing the login message.

**Parameters**:

* `activeAddress` (string): The user's active multiaccount wallet address.

**Response:**

```json
{
 "nonce": "string"
}
```

### User Login

**Endpoint**: `POST /login`

* **Description**: Authenticates the user and retrieves an access token. The nonce is obtained in the previous API call. The access token is saved to the browser locally, meaning the user won't have to log in again after closing and reopening the browser.

**Request Body:**

```json
{
 "account_address": "string",
 "expiration_time": "ISO8601 datetime string",
 "issued_at": "ISO8601 datetime string",
 "signature": "string",
 "nonce": "string"
}
```

**Response:**

```json
{
 "access_token": "string"
}
```

### Get Pending Instant Open Requests

**Endpoint**: `GET /instant_open/{account_address}`

Description: This endpoint retrieves a statement for all pending instant open requests for a given account.

**Parameters**:

* `account_address` (string): The user's multi-account wallet address.

**Response**: A list of pending instant open requests for the given account. Each object in the list contains details of the requested positions.

### Response Schema:

```json
[
  {
    "position_type": 0 // 0 for long, 1 for short,
    "temp_quote_id": "string",
    "symbol_id": "string",
    "requested_open_price": "string",
    "quantity": "string",
    "party_a_address": "string",
    "cva": "string",
    "partyAmm": "string",
    "partyBmm": "string",
    "lf": "string",
    "order_type": 0 // 0 for limit, one for market
  }
]
```

## Instant Actions

These endpoints allow solvers to execute instant open and close actions on the user's behalf.

### Instant Open Position

**Endpoint**: `POST /instant_open`

Opens a position instantly on behalf of the user. The user’s account balance is checked, including allocated balance, unrealized PnL, and locked amounts (cva, lf, partyAmm). If the user has too many pending instant RFQs, or if their available balance does not cover the new RFQ's requirements, the request should be rejected.

A temporary quote ID is generated, and the necessary request data is emitted and stored in Redis. The request is registered as a pending instant open action (stored in the InstantRFQs table).

**Response:**

Upon successful registration, the details of the newly created instant RFQ are returned, including position type, symbol ID, quote ID, and other relevant data.

**Request Body:**

```json
{
 "symbolId": "string",
 "positionType": 0, // 0 for long, 1 for short
 "orderType": 0,    // 0 for limit, 1 for market
 "price": "string",
 "quantity": "string",
 "cva": "string",
 "lf": "string",
 "partyAmm": "string",
 "partyBmm": "string",
 "maxFundingRate": "string",
 "deadline": 1625234523 // Unix timestamp
}
```

**Headers:**

```json
headers: {
   "Content-Type": "application/json",
   Authorization: `Bearer ${token}`,
},
```

**Response:**

```json
[
  {
    "position_type": 0 // 0 for long, 1 for short,
    "temp_quote_id": "string",
    "symbol_id": "string",
    "requested_open_price": "string",
    "quantity": "string",
    "party_a_address": "string",
    "cva": "string",
    "partyAmm": "string",
    "partyBmm": "string",
    "lf": "string",
    "order_type": 0 // 0 for limit, one for market
  }
]

```

This response includes the temporary `temp_quote_id` which allows the system to track the quote before it is confirmed on-chain. Once confirmed, the real `quote_id` will be resolved and stored.

How Temporary Quote IDs Work:

* A temporary quote ID is generated as a negative decremental integer when the instant open request is made.
* The temporary quote ID is used to track the status of the position until the actual on-chain `quote_id` is confirmed.
* Once the on-chain transaction is confirmed, the real `quote_id` replaces the temporary one.
* The position state endpoint will provide the real `quote_id` after the resolution, allowing the user to track the final status.

### Instant Close Position

**Endpoint**: `POST /instant_close`

* Description: Closes an open position instantly on behalf of the user. The API checks the validity of the request based on the user's access, the state of the position, and available balance The close is always processed as a MARKET order.

**Request Body:**

```json
{
 "quote_id": number,
 "quantity_to_close": "string",
 "close_price": "string"
}
```

**Headers:**

```json
headers: {
   "Content-Type": "application/json",
   Authorization: `Bearer ${token}`,
},
```

**Response:**

```json
{
 "successful": "boolean",
 "message": "string"
}
```

### Get Instant Close Requests

**Endpoint:** `GET /instant_close/{account_address}`

Description: Retrieves all pending instant close requests for the provided user's account (`account_address`). The system returns a list of pending close requests for both instant close requests and any regular close requests that are still being processed.

**Headers:**

```json
{
  "Authorization": `Bearer ${token}`   // Access token obtained during login
}
```

**Response:**

```json
[
  {
    "quote_id": number,             
    "quantity_to_close": "string",  
    "close_price": "string"           },
  {
    "quote_id": number,
    "quantity_to_close": "string",
    "close_price": "string"
  }
]
```

### Cancel Instant Action

**Endpoints**:

* `DELETE /instant_close/{quoteId}`
* `DELETE /instant_open/{quoteId}`

**Description**: Cancel an open or close request.

**Parameters**:

* `quoteId` (integer): The temporary ID of the instant quote to be canceled.

**Headers**:

```json
headers: {
   "Content-Type": "application/json",
   Authorization: `Bearer ${token}`,
},
```

**Response:**

```json
{
 "successful": "boolean",
 "message": "string"
}
```

## Contract Calls for Instant Trading

In order to implement instant actions it’s necessary for the user to call `delegateAccess()` on the MultiAccount contract for the respective sub-account to the partyB address, which performs actions on behalf of the user. This transaction should include the function signatures which partyB needs access to for instant trading.

To execute functions on behalf of partyA, the partyB should use the `_call()` function on the MultiAccount contract and pass the partyA address as a parameter with the `_callDatas`. 

 After this step the user should then sign the message from the solver. 

### Instant Open

For Instant Opens, `delegateAccess()` should be called from the trader’s wallet with the following parameters:

* `account` (address): The User’s sub-account
* `target` (address) : The address of the PartyB
* `selector` (bytes4\[]):  `0x7f2755b2` (Function selector for sendQuote) AND `0x40f1310c` (Function selector for sendQuoteWithAffiliate)
* `state` (bool): true

### Instant Close

For Instant Close, delegateAccess() should be called from the trader’s wallet with the following parameters:

* `account`(address): The User’s sub-account
* `target`(address) : The address of the PartyB
* `selector`(bytes4\[]): 0x501e891f (Function selector for requestToClosePosition)
* `state` (bool): true<br>