> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/omniston/resolvers/guide.md).

# Resolver integration

Enroll, authenticate, and implement current v1beta8 quote and order events on a bidirectional gRPC stream.

Integrate a resolver through `stonfi.omni.v1beta8.ResolverRpc` to receive RFQs, return quotes, and settle accepted orders. Register your resolver and authorize its keys before connecting.

## Registration Process

### Step 1: Generate Keys

First, generate one or more Ed25519 key pairs that will be used for authentication:

{% hint style="success" %}
[JavaScript implementation](https://github.com/3nsoft/ecma-nacl)
{% endhint %}

{% hint style="success" %}
[Rust implementation](https://github.com/3nsoft/rust-nacl)
{% endhint %}

{% hint style="info" %}
For other languages, you can use any standard Ed25519 implementation library available in your preferred programming language
{% endhint %}

### Step 2: Prepare Metadata

Create a JSON document containing:

* Your resolver name
* Your public key(s)

Example:

```json
{
  "name": "MyResolver",
  "publicKeys": [
    "b951254b184fae6906a61ab01e37296fbb28961494cacf7befac9f638fcfe40c",
    "9397ddd52a0d6033da4a32e654b4afbddcc5d832575e396c0a6f5b213faa199f"
  ]
}
```

### Step 3: Submit Registration

{% hint style="success" %}
[Link to google form](https://forms.gle/LxY2GphQdyhLu3L39)
{% endhint %}

1. Your metadata will be stored in an SBT NFT collection
2. You'll receive your SBT stake address for API authentication

## Generate the current resolver client

Generate bindings from the complete [resolver protobuf tree](https://github.com/ston-fi/stonfi-proto/tree/main/proto/stonfi/omni/v1beta8/resolver), including common/trader/type imports. Connect with TLS to the gRPC target in [Environments and endpoints](/developer-section/omniston/environments.md).

The service is `stonfi.omni.v1beta8.ResolverRpc/Open`: one bidirectional stream of `ResolverRequest` and `ResolverEvent`.

## Authenticate

The first request must contain `connect`. Serialize `AuthenticationPayload` with the service's required timestamp and your enrolled `stake_address`; sign those exact bytes with the authorized Ed25519 key.

```protobuf
message AuthenticationPayload {
  uint64 connect_timestamp = 1;
  string stake_address = 2;
}

message ConnectRequest {
  bytes serialized_authentication_payload = 1;
  bytes public_key = 2;
  bytes signature = 3;
}
```

Construct the generated `ResolverRequest` with a unique `seqno` and `connect`. Native gRPC bytes fields contain bytes; base64 is their JSON representation, not a different signature format. Do not sign JSON or a deserialize/reserialize variant of the payload.

Wait for `connected`. Set a connection timeout of 10-30 seconds and reconnect when it expires without a `connected` event. Fatal authentication failures close the gRPC stream. Resolver authentication uses the enrolled keys and stake address.

## Correlate requests and events

`seqno` identifies a new request/event; `reply_to` references its counterpart. Use a monotonic request counter and reply with the server event ID where the protocol requires a reply. Do not substitute RFQ IDs for stream sequence numbers.

Current request branches are `connect`, `sign_resolver_address`, `update_quote`, and `invalidate_quote`. Event branches include `connected`, `resolver_address_signed`, `quote_requested`, `quote_request_cancelled`, `quote_accepted`, `quote_rejected`, `quote_invalidated`, `order_updated`, `order_closed`, `execution_updated`, and `keep_alive`.

## Handle an RFQ and provide a quote

`QuoteRequestedEvent` contains the original `quote_request`, its `rfq_id`, timing/protocol parameters, and a resolver amount branch:

* With `resolver_receives_units`, preserve that required input and calculate the offered output.
* With `resolver_sends_units`, preserve that required output and calculate the input required to provide it.

Amounts are integer asset units. Calculate `resolver_sends_units` as the trader's output plus the protocol and integrator fees specified in the event.

Send `update_quote` containing an `UpdateQuoteRequest`:

```protobuf
message ResolverQuote {
  stonfi.common.v1.ChainAddress resolver_src_address = 1;
  string resolver_receives_units = 2;
  stonfi.common.v1.ChainAddress resolver_dst_address = 3;
  string resolver_sends_units = 4;
  uint64 trade_start_deadline = 5;
}

message UpdateQuoteRequest {
  string rfq_id = 1;
  ResolverQuote quote = 10;
}
```

Set valid source/destination addresses matching the RFQ asset chains. Observe the requested settlement branch, protocol parameters, and trade-start deadline.

Handle acceptance, rejection, RFQ cancellation, and invalidation. Branch on `QuoteRejectedEvent.code`; its human-readable message is for diagnostics. Use `invalidate_quote` when a previously offered quote is no longer executable. Quote acceptance acknowledges the quote; order and execution events report settlement progress.

## Order fulfilment and recovery

`order_updated` includes the quote, `remaining_input_units`, available HTLC secret count, cancellation timing, exclusivity, and serialized order details. Reservations may temporarily reduce the remaining amount and then expire; zero currently available input is not by itself a terminal completion signal.

Follow the selected settlement contract's reserve/fill/complete/rollback interface. HTLC output liquidity and disclosure timing must follow [Settlement lifecycle](/developer-section/omniston/how-omniston-works.md); do not assume an RFQ quote-submission method also executes an order on-chain. Use `sign_resolver_address` where the protocol requires an authorized resolver-address signature.

Handle non-fatal protocol events separately from fatal gRPC errors. Record RFQ, quote, order, execution, and stream correlation IDs in logs. After reconnecting, authenticate again and recover actual settlement state before generating new fulfilment transactions. Use [History](/developer-section/omniston/history.md) for finalized reporting, not live settlement.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/omniston/resolvers/guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.