feat(ecosystem): add SparkDEX, Sceptre, Kinetic, Cyclo, Firelight, and Stargate connectors

README.md

@@ -14,7 +14,7 @@ SDK for building **verifiable AI Agents** on Flare using Confidential Space Trus
 - **Verifiable execution**: Run logic inside Intel TDX TEEs via [GCP Confidential Space](https://cloud.google.com/confidential-computing/confidential-space/docs/confidential-space-overview).
 - **Multi-agent consensus**: Majority/Tournament/[Consensus Learning](https://arxiv.org/abs/2402.16157) via [Google Agent2Agent](https://github.com/a2aproject/A2A) protocol.
 - **Agent framework**: Built on [Google ADK](https://google.github.io/adk-docs/) with tool-calling, orchestration and evaluation.
-- **Flare integration**: [FTSO](https://dev.flare.network/ftso/overview), [FDC](https://dev.flare.network/fdc/overview), [FAssets](https://dev.flare.network/fassets/overview) + ecosystem dApps ([Sceptre](https://sceptre.fi), [SparkDEX](https://sparkdex.ai), ...).
+- **Flare integration**: [FTSO](https://dev.flare.network/ftso/overview), [FDC](https://dev.flare.network/fdc/overview), [FAssets](https://dev.flare.network/fassets/overview) + ecosystem dApps ([SparkDEX](https://sparkdex.ai), [Sceptre](https://sceptre.fi), [Kinetic](https://www.kinetic.market/), [Cyclo](https://www.cyclo.xyz/), [Firelight](https://www.firelight.fi/), [Stargate](https://stargate.finance/)).
 - **Social connectors**: X, Telegram, Farcaster.
 
 ## 🏗️ Architecture
@@ -50,7 +50,7 @@ flowchart TD
         F --> PR[Protocols]
         PR --o PROTOS["FTSO<br>FDC<br>FAssets"]
         F --> AP[Applications]
-        AP --o APPS[SparkDEX<br>OpenOcean<br>Kinetic<br>Cyclo]
+        AP --o APPS[SparkDEX<br>Sceptre<br>Kinetic<br>Cyclo<br>Firelight<br>Stargate]
     end
 
     %% Social Engine subgraph

docs/cyclo_readme.md

@@ -0,0 +1,187 @@
+# Cyclo Connector
+
+The Cyclo connector provides an interface to interact with the Cyclo protocol on Flare for non-liquidating leverage.
+
+## Overview
+
+Cyclo allows users to lock collateral (sFLR) and mint cy* tokens (cysFLR) without liquidation risk. The cy* tokens trade between $0-$1 and can be used to create leverage or as stable-value alternatives.
+
+## Contract Addresses (Flare Mainnet)
+
+- **cysFLR Vault**: `0x19831cfB53A0dbeAD9866C43557C1D48DfF76567`
+- **cysFLR Receipt (ERC1155)**: `0xd387FC43E19a63036d8FCeD559E81f5dDeF7ef09`
+
+## How It Works
+
+1. **Lock & Mint**: User locks sFLR → mints cysFLR + receipt NFT
+   - Receipt ID = price at time of lock (e.g., 0.015 USD per sFLR)
+   - User gets cysFLR tokens (ERC20) that trade $0-$1
+
+2. **Trade**: User can sell cysFLR to create leverage
+   - Example: Lock 100 sFLR → get 100 cysFLR @ $0.80 → sell for 80 sFLR → lock again
+
+3. **Unlock**: User buys back cysFLR + burns with receipt NFT → unlocks sFLR
+   - Must burn SAME amount of cysFLR as receipt balance
+   - Receipt ID determines redemption ratio
+
+## Basic Usage
+
+### Initialize
+
+```python
+from flare_ai_kit import FlareAIKit
+from flare_ai_kit.ecosystem.applications.cyclo import Cyclo
+
+kit = FlareAIKit(None)
+cyclo = await Cyclo.create(kit.settings.ecosystem)
+```
+
+### Lock sFLR & Mint cysFLR
+
+```python
+# Lock 10 sFLR to mint cysFLR
+tx_hash = await cyclo.deposit_sflr(
+    assets=10 * 10**18,  # 10 sFLR (18 decimals)
+    recipient="0xYourAddress",
+    min_share_ratio=0,  # Slippage protection
+    receipt_info=b"",   # Optional metadata
+)
+```
+
+### Burn cysFLR & Unlock sFLR
+
+```python
+# Burn 5 cysFLR + receipt to unlock sFLR
+tx_hash = await cyclo.redeem_sflr(
+    shares=5 * 10**18,       # 5 cysFLR to burn
+    recipient="0xYourAddress",
+    owner="0xYourAddress",
+    receipt_id=15000000000000000000,  # ID from deposit
+    receipt_info=b"",
+)
+```
+
+### Check Balances
+
+```python
+# Get cysFLR balance
+balance = await cyclo.get_cysflr_balance("0xYourAddress")
+print(f"cysFLR: {balance / 10**18}")
+
+# Get receipt balance for specific ID
+receipt_balance = await cyclo.get_receipt_balance(
+    "0xYourAddress",
+    receipt_id=15000000000000000000
+)
+print(f"Receipt NFTs: {receipt_balance}")
+```
+
+### Query Vault Info
+
+```python
+# Get underlying asset (sFLR address)
+asset = await cyclo.get_vault_asset()
+print(f"Vault asset: {asset}")
+```
+
+## Function Reference
+
+### `deposit_sflr()`
+
+Lock sFLR and mint cysFLR tokens + receipt NFT.
+
+**Parameters:**
+- `assets` (int): Amount of sFLR to lock (in wei, 18 decimals)
+- `recipient` (str): Address to receive cysFLR and receipt
+- `min_share_ratio` (int, optional): Minimum share ratio for slippage protection (default: 0)
+- `receipt_info` (bytes, optional): Optional metadata for receipt (default: b"")
+
+**Returns:** Transaction hash (str)
+
+**Raises:** `CycloError` if deposit fails
+
+---
+
+### `redeem_sflr()`
+
+Burn cysFLR tokens + receipt NFT to unlock sFLR.
+
+**Parameters:**
+- `shares` (int): Amount of cysFLR to burn (in wei, 18 decimals)
+- `recipient` (str): Address to receive unlocked sFLR
+- `owner` (str): Address that owns the cysFLR tokens and receipt NFT
+- `receipt_id` (int): ID of the receipt NFT (price at time of lock)
+- `receipt_info` (bytes, optional): Optional metadata (default: b"")
+
+**Returns:** Transaction hash (str)
+
+**Raises:** `CycloError` if redemption fails
+
+---
+
+### `get_cysflr_balance()`
+
+Get cysFLR token balance for an address.
+
+**Parameters:**
+- `address` (str): Address to check balance for
+
+**Returns:** Balance in wei (int, 18 decimals)
+
+**Raises:** `CycloError` if query fails
+
+---
+
+### `get_receipt_balance()`
+
+Get receipt NFT balance for a specific ID.
+
+**Parameters:**
+- `address` (str): Address to check balance for
+- `receipt_id` (int): ID of the receipt NFT
+
+**Returns:** Number of receipt NFTs with this ID (int)
+
+**Raises:** `CycloError` if query fails
+
+---
+
+### `get_vault_asset()`
+
+Get the underlying asset address (sFLR) for the vault.
+
+**Returns:** Checksum address of the underlying asset (ChecksumAddress)
+
+**Raises:** `CycloError` if query fails
+
+## Example Script
+
+See [`examples/09_cyclo_leverage.py`](../examples/09_cyclo_leverage.py) for a complete example.
+
+## Notes
+
+- **Receipt IDs**: Track receipt IDs from deposit events - you'll need them to redeem
+- **Approvals**: Approve sFLR spending before deposit
+- **No Liquidations**: Unlike traditional lending, Cyclo never liquidates your position
+- **Price Bound**: cysFLR trades between $0-$1, creating natural leverage limits
+- **Staking Rewards**: Locked sFLR continues earning staking rewards
+
+## Error Handling
+
+All functions raise `CycloError` on failure. Wrap calls in try/except:
+
+```python
+from flare_ai_kit.common import CycloError
+
+try:
+    tx_hash = await cyclo.deposit_sflr(10 * 10**18, recipient)
+except CycloError as e:
+    print(f"Deposit failed: {e}")
+```
+
+## Learn More
+
+- **Cyclo Docs**: https://cyclo.finance
+- **Mechanism**: Lock collateral → mint cy* tokens → no liquidations
+- **Use Cases**: Non-liquidating leverage, stable-value tokens, yield strategies
+

docs/firelight_readme.md

@@ -0,0 +1,160 @@
+# Firelight Connector
+
+The Firelight connector enables XRP staking on Flare Network, allowing users to stake wrapped XRP (FXRP) to earn rewards while providing DeFi coverage.
+
+## Overview
+
+Firelight is a protocol for DeFi cover that transforms staked XRP into protection for DeFi protocols. Users stake FXRP and receive stXRP, a liquid staking token that can be used across DeFi applications.
+
+## Contract Information
+
+| Item | Value |
+|------|-------|
+| **stXRP Vault Address** | `0x4C18Ff3C89632c3Dd62E796c0aFA5c07c4c1B2b3` |
+| **Protocol** | ERC4626 Vault with Withdrawal Periods |
+| **Network** | Flare Mainnet |
+
+## Usage
+
+### 1. Initialize the Connector
+
+```python
+from flare_ai_kit.ecosystem import Firelight
+from flare_ai_kit.ecosystem.settings import EcosystemSettings
+
+settings = EcosystemSettings(
+    wallet_address="YOUR_WALLET_ADDRESS",
+    private_key="YOUR_PRIVATE_KEY",
+)
+
+firelight = await Firelight.create(settings)
+```
+
+### 2. Stake FXRP (XRP)
+
+```python
+# Amount in wei (18 decimals)
+amount = 100 * 10**18  # 100 FXRP
+
+# IMPORTANT: Approve vault to spend your FXRP first!
+# fxrp_contract.approve(firelight.STXRP_VAULT, amount)
+
+tx_hash = await firelight.stake_xrp(amount)
+print(f"Staked! TX: {tx_hash}")
+```
+
+### 3. Request Withdrawal
+
+```python
+# Request withdrawal (must wait 1 period before claiming)
+amount = 50 * 10**18  # 50 FXRP
+
+tx_hash = await firelight.request_withdrawal(amount)
+print(f"Withdrawal requested! TX: {tx_hash}")
+```
+
+### 4. Claim Withdrawal
+
+```python
+# Get current period
+current_period = await firelight.get_current_period()
+
+# Claim from previous period
+tx_hash = await firelight.claim_withdrawal(current_period - 1)
+print(f"Claimed! TX: {tx_hash}")
+```
+
+### 5. Check Balances
+
+```python
+# Check stXRP balance
+balance = await firelight.get_stxrp_balance("0xYourAddress")
+print(f"stXRP Balance: {balance / 10**18}")
+
+# Check total staked in vault
+total = await firelight.get_total_assets()
+print(f"Total Staked: {total / 10**18} FXRP")
+```
+
+### 6. Check Pending Withdrawals
+
+```python
+# Get current period
+period = await firelight.get_current_period()
+
+# Check pending amount for previous period
+pending = await firelight.get_pending_withdrawal(period - 1, "0xYourAddress")
+print(f"Pending: {pending / 10**18} FXRP")
+```
+
+## How It Works
+
+1. **Stake**: Deposit FXRP to receive stXRP (liquid staking token)
+2. **Earn**: stXRP represents your staked FXRP + rewards
+3. **Use**: Trade or use stXRP in DeFi while still earning
+4. **Withdraw**: Request withdrawal → wait 1 period → claim FXRP
+
+## Withdrawal Periods
+
+- Firelight uses **withdrawal periods** for security
+- When you request a withdrawal, it becomes claimable in the **next period**
+- Check `currentPeriod()` to see the active period
+- Claim using `claimWithdraw(period)` after the period ends
+
+## Important Notes
+
+### Before Staking
+
+⚠️ **You need FXRP (wrapped XRP on Flare)**:
+- Get FXRP through Flare's FAssets bridge
+- Or swap for FXRP on Flare DEXes
+
+⚠️ **You must approve the vault to spend your FXRP**:
+
+```python
+# Using web3.py (example)
+fxrp_contract = w3.eth.contract(address=FXRP_ADDRESS, abi=ERC20_ABI)
+tx = fxrp_contract.functions.approve(
+    firelight.STXRP_VAULT,
+    amount
+).build_transaction({...})
+```
+
+### What is stXRP?
+
+- **stXRP** is an ERC20 liquid staking token
+- Represents your staked FXRP in the vault
+- Can be transferred, traded, or used in DeFi
+- Earn rewards while your FXRP is staked
+
+### DeFi Cover
+
+Firelight provides **on-chain risk protection** for DeFi:
+- Your staked XRP backs DeFi protocol coverage
+- Earn fees from cover buyers
+- Help secure the Flare DeFi ecosystem
+
+## Error Handling
+
+The connector raises `FirelightError` for protocol-specific errors:
+
+```python
+from flare_ai_kit.common import FirelightError
+
+try:
+    await firelight.stake_xrp(amount)
+except FirelightError as e:
+    print(f"Firelight error: {e}")
+```
+
+## Additional Resources
+
+- [Firelight Website](https://firelight.finance/)
+- [Firelight Docs](https://docs.firelight.finance/)
+- [FlareScan - stXRP Vault](https://flarescan.com/address/0x4C18Ff3C89632c3Dd62E796c0aFA5c07c4c1B2b3)
+- [Example Script](../examples/12_firelight_xrp_staking.py)
+
+## XRP Gang! 🚀
+
+Stake your XRP, earn rewards, and support DeFi security on Flare!
+