Flyover SDK - Trusted Accounts

Note

If you wish to suggest changes on this document, please open a PR on the Liquidity Provider Server Repository

🧠 Summary

The Liquidity Provider Trusted Accounts feature extends the existing Liquidity Provider Server (LPS) and FlyoverSDK to allow Liquidity Providers (LPs) to configure a set of trusted Rootstock accounts that can bypass certain validation checks — such as the reCAPTCHA verification — during PegIn or PegOut operations.

This functionality is part of the Flyover Protocol, aimed at enabling automated integrations for partners and liquidity providers who operate frequently.

---

🏗 Architecture and Design

Components

This feature adds functionality to two existing components:

1. Liquidity Provider Server (LPS) – Enables LPs to configure and manage trusted accounts with BTC/RBTC locking caps.
2. FlyoverSDK – Provides new methods that allow integrators to sign and submit quotes authenticated by trusted accounts.

Design Notes

• Backward compatible with existing FlyoverSDK versions >= v1.7.0 and LPS versions >= v2.3.0.
• The account paying for the operation doesn’t need to be the same as the whitelisted account, but a valid signature of the quote hash from the trusted account must be provided.

---

⚙️ Setup and Configuration

Environment Requirements

• FlyoverSDK: >= v1.70
• LPS: >= v2.3.0

Configuration

• The LP must configure authorized trusted accounts in their LPS instance.
• No additional .env variables or feature flags are required.

---

🔌 API / Interface Details

FlyoverSDK Methods

• async acceptAuthenticatedQuote(quote: Quote, signature: string): Promise<AcceptedQuote>: Accepts a PegIn quote authenticated by a trusted account’s signature.
• async acceptAuthenticatedPegoutQuote(quote: PegoutQuote, signature: string): Promise<AcceptedPegoutQuote>: Accepts a PegOut quote authenticated by a trusted account’s signature.
• async signQuote(quote: Quote | PegoutQuote): Promise<string>: Generates a valid signature for a given quote using the whitelisted Rootstock account.

Input / Output

Same input and output as acceptQuote and acceptPegoutQuote. The difference is that these methods require a signature parameter, obtained via:

• The signQuote() SDK method, or
• A manually created signature by the SDK integrator.

Possible errors

Both error types are raised as FlyoverError instances:

Error Scenario	Description
Invalid Signature	The provided signature does not match a whitelisted account.
Locking Cap Exceeded	The account exceeded its assigned BTC/RBTC locking cap.

---

🧭 Integration Guide

To integrate this feature:

1. Ensure you are using FlyoverSDK >= v1.70.
2. Obtain a whitelisted Rootstock account from your Liquidity Provider.
3. Use the SDK’s signQuote method to sign your quote hash.
4. Use the authenticated accept method (acceptAuthenticatedQuote or acceptAuthenticatedPegoutQuote) with the quote and signature.
5. The LP’s LPS instance will validate the signature against its trusted accounts configuration.

🔐 Only accounts whitelisted by an LP will be accepted. Each account has a configured BTC/RBTC locking cap that restricts usage volume.

Authentication

Trust is based solely on account whitelisting and signature verification.

Integration Entry Points

• Primary integration via FlyoverSDK
• No direct API calls required

---

🧪 Testing

Local Testing Setup

• Deploy a local LPS instance.
• Configure one or more trusted accounts.
• Test using the new SDK methods with valid and invalid signatures to validate expected behavior.

Test Utilities

Example tests and automation demos can be found in: 🔗 Flyover SDK Automation Demo

Notes

Follow the documentation in the above repository for commands and setup steps.

---

🧾 Changelog

Component	Version	Release Link
FlyoverSDK	v1.7.0	GitHub Release
LPS	v2.3.0	GitHub Release

---

📦 Related Resources

• Flyover SDK (npm): @rsksmart/flyover-sdk
• GitHub Repo: Flyover SDK