Skip to content

Commit d691c29

Browse files
fasskofassko
committed
feat(docs): create AGENTS.md to provide comprehensive guidelines for explaining Flare and its protocols for AI agents reading this repo
1 parent 38fd093 commit d691c29

1 file changed

Lines changed: 149 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# AGENTS.md
2+
3+
## Purpose
4+
5+
This file gives AI agents the core framing to explain Flare correctly.
6+
Use it when writing, editing, or reviewing Flare content in this repository.
7+
Prioritize conceptual accuracy over marketing shorthand.
8+
9+
## What Flare Is
10+
11+
- Flare is an EVM-compatible Layer 1 blockchain.
12+
- Its key differentiator is enshrined data: core data protocols are built into the network rather than added as third-party infrastructure.
13+
- Flare is designed for data-intensive and interoperable applications.
14+
- Flare uses Avalanche Snowman++ consensus and targets roughly 1.8 second block times with single-slot finality.
15+
16+
## Core Message
17+
18+
When explaining Flare, lead with this idea:
19+
20+
- Flare is not just another EVM chain.
21+
- Flare combines smart contracts with protocol-level data acquisition and verification.
22+
- The main reason to build on Flare is access to decentralized data protocols that are native to the network.
23+
24+
## Core Protocols
25+
26+
### FTSO
27+
28+
- FTSO stands for Flare Time Series Oracle.
29+
- It provides decentralized data feeds, especially price feeds.
30+
- It is protocol-native, not a bolted-on oracle network.
31+
- Prefer FTSOv2 terminology and interfaces for current developer content.
32+
- Use it when describing onchain access to timely market data.
33+
- FTSO feeds are provided by decentralized data providers who submit price estimates that are aggregated on-chain.
34+
35+
### FDC
36+
37+
- FDC stands for Flare Data Connector.
38+
- It lets contracts verify data from external chains and Web2 sources through attestations produced by the Flare Data Connector system.
39+
- Use it when the topic is external data verification, cross-chain state, or proving real-world events onchain.
40+
- Do not introduce new references to deprecated State Connector terminology unless the page is explicitly historical or migration-focused.
41+
42+
### FAssets
43+
44+
- FAssets are trust-minimized representations of non-smart-contract assets such as XRP or BTC on Flare.
45+
- Their purpose is to bring otherwise non-programmable assets into DeFi and smart contract workflows.
46+
- When explaining FAssets, mention agents, collateral, minting, redemption, and liquidation as core mechanics.
47+
48+
### Smart Accounts
49+
50+
- Smart Accounts provide account abstraction features that simplify user interaction with Flare.
51+
- They are especially useful for XRPL users interacting with Flare-based applications.
52+
53+
## Supported Networks
54+
55+
Use the correct network for the context:
56+
57+
- Flare Mainnet: production network, chain ID `14`
58+
- Coston2: primary dApp testnet, chain ID `114`
59+
- Songbird: canary network for live testing and protocol experimentation, chain ID `19`
60+
- Coston: protocol-focused test network, chain ID `16`
61+
62+
If the content is for developers building apps, default to Coston2 for examples unless the page is explicitly about production deployment.
63+
64+
Examples should align with official RPC endpoints documented in the Flare Developer Hub.
65+
66+
## Package Guidance
67+
68+
Prefer interfaces and registry resolution rather than hardcoding protocol contract addresses.
69+
70+
### Solidity
71+
72+
- Prefer `@flarenetwork/flare-periphery-contracts` for Solidity interfaces and network-specific imports.
73+
- Prefer the `ContractRegistry` pattern over hardcoded addresses.
74+
- Use network-specific imports such as `@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol`.
75+
- If the topic is FAssets, use the official Flare FAssets contracts or interfaces already referenced by the docs and examples instead of inventing alternative wrappers.
76+
77+
### Offchain Scripts
78+
79+
- Prefer `@flarenetwork/flare-periphery-contract-artifacts` for ABI access in scripts and tooling.
80+
- Prefer official Flare package ABIs and interfaces over copied ABI blobs or unofficial packages.
81+
- Never invent contract addresses. Use runtime contract resolution where available, or clearly sourced documented addresses.
82+
83+
### React And Frontend Integrations
84+
85+
- Prefer `wagmi`, `viem`, and `@flarenetwork/flare-wagmi-periphery-package` for modern React integrations where appropriate.
86+
- If an existing example already uses Hardhat or `ethers`, preserve local consistency unless the task is explicitly to modernize it.
87+
88+
## Terminology Rules
89+
90+
- Distinguish Flare Mainnet from Songbird and Coston2. Do not treat them as interchangeable.
91+
- Distinguish FTSO, FDC, FAssets, and Smart Accounts clearly. Do not collapse them into one generic oracle or bridge system.
92+
- Use "data providers" or "providers" consistently when discussing FTSO or FSP participants.
93+
- Avoid saying things happen automatically without explaining who triggers the transaction and why.
94+
95+
## Explanation Style
96+
97+
When explaining Flare, optimize for mechanisms:
98+
99+
- Explain what the protocol does.
100+
- Explain who participates.
101+
- Explain what data or asset moves through the system.
102+
- Explain how the result becomes usable by a smart contract or developer.
103+
104+
Prefer:
105+
106+
- "FDC verifies external data through attestations that contracts can consume."
107+
- "FAssets let XRP, BTC, and similar assets be used in Flare DeFi through a collateralized mint and redemption system."
108+
109+
Avoid vague phrasing like:
110+
111+
- "Flare connects everything."
112+
- "Flare brings data to blockchain" without naming which protocol does it.
113+
- "Flare wraps assets" without explaining the collateral and agent model.
114+
115+
## Important Mental Models
116+
117+
- Nothing is automatic onchain. If a state transition matters, explain who calls the function and why.
118+
- Incentives matter. For systems like FAssets, liquidation and collateral mechanics are not implementation details; they are part of why the system works.
119+
- Do not imply offchain data is trusted blindly. For Flare, stress verification, attestations, consensus, and proofs where relevant.
120+
- Do not hardcode addresses in examples if the proper Flare pattern is runtime contract resolution.
121+
122+
## Safe Defaults For Developer Content
123+
124+
- Prefer Coston2 in starter examples.
125+
- Mention that Flare supports modern EVM tooling and Solidity development.
126+
- If contract access is discussed, prefer the `ContractRegistry` pattern over hardcoded addresses.
127+
- If network setup is discussed, ensure the example network, chain ID, and RPC align.
128+
- If the topic is price feeds, start with FTSO.
129+
- If the topic is proving external events or external chain activity, start with FDC.
130+
- If the topic is BTC, XRP, or DOGE utility on Flare, start with FAssets.
131+
- If the topic is wallet UX for XRPL users, start with Smart Accounts.
132+
133+
## Common Mistakes To Avoid
134+
135+
- Do not describe Flare as just an oracle network.
136+
- Do not describe FDC as a generic bridge.
137+
- Do not describe FAssets as simple custodial wrapped tokens.
138+
- Do not imply Songbird is the same as mainnet.
139+
- Do not use Ethereum assumptions blindly if Flare-specific infrastructure exists and is the point of the page.
140+
- Do not write examples that contradict Flare's actual network progression or protocol roles.
141+
- Do not mix deprecated and current protocol names without making the distinction explicit.
142+
143+
## Handoff Expectations
144+
145+
When you finish Flare-related content work:
146+
147+
- State which Flare concept or protocol you clarified.
148+
- Mention any terminology you normalized.
149+
- Call out any assumptions you made about network, protocol, or developer audience.

0 commit comments

Comments
 (0)