fix(docs): add enhancement to the FDC guides

docs/fdc/attestation-types/address-validity.mdx

@@ -1,21 +1,20 @@
 ---
 title: AddressValidity
-description: Assertion whether a given string represents a valid address on an external blockchain.
+description: Validates if a string is a legitimate external blockchain address.
 keywords: [fdc, oracle, flare-data-connector, flare-network]
 sidebar_position: 1
 ---
 
 import Addresses from "./_addresses.mdx";
-import IAddressValidity from "../reference/IAddressValidity.mdx";
 
 Assertion whether a given string represents a **valid address** on an external blockchain.
 
 ## Supported chains
 
-- `BTC` (Bitcoin)
-- `DOGE` (Dogecoin)
-- `XRP` (XRP Ledger)
-- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
+| Network Type | Supported Chains                                       |
+| ------------ | ------------------------------------------------------ |
+| **Mainnet**  | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
+| **Testnet**  | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`  |
 
 ## Request
 
@@ -53,6 +52,6 @@ For the `lowestUsedTimestamp` parameter, the value `0xffffffffffffffff` (equival
 
 <Addresses />
 
-## Contract interface
+## Contract Interface
 
-<IAddressValidity />
+For the complete interface definition, see [`IAddressValidity`](/fdc/reference/IAddressValidity.mdx).

docs/fdc/attestation-types/balance-decreasing-transaction.mdx

@@ -1,6 +1,6 @@
 ---
 title: BalanceDecreasingTransaction
-description: Detects a transaction that either decreases the balance of a specified address.
+description: Detects a transaction decreasing the balance of an address.
 keywords: [fdc, oracle, flare-data-connector, flare-network]
 sidebar_position: 2
 ---
@@ -9,21 +9,20 @@ import Finality from "./_finality.mdx";
 import StandardAddressHash from "./_standard_address_hash.mdx";
 import TransactionSuccessStatus from "./_transaction_success_status.mdx";
 import StandardPaymentReference from "./_standard_payment_reference.mdx";
-import IBalanceDecreasingTransaction from "../reference/IBalanceDecreasingTransaction.mdx";
 
 Information describing a transaction that either **decreases the balance** for a specified address.
 
-A transaction is considered “balance decreasing” for the specified address if:
+A transaction is considered "balance decreasing" for the specified address if:
 
 1. The balance **after the transaction** is lower than **before**.
 2. The address is among the **signers** of the transaction (even if its balance is not reduced).
 
 ## Supported chains
 
-- `BTC` (Bitcoin)
-- `DOGE` (Dogecoin)
-- `XRP` (XRP Ledger)
-- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
+| Network Type | Supported Chains                                       |
+| ------------ | ------------------------------------------------------ |
+| **Mainnet**  | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
+| **Testnet**  | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`  |
 
 ## Request
 
@@ -58,16 +57,26 @@ The verification process is chain-specific and can be computed with a [balance d
 
 ### UTXO chains (Bitcoin and Dogecoin)
 
+#### Address Indication
+
 - `sourceAddressIndicator`: Represents the index of the transaction input, formatted as a **0x-prefixed 32-byte string**.
   - If the specified input does not exist or lacks an associated address, the attestation request is rejected.
+
+#### Data Calculation
+
 - `sourceAddress`: Address associated with the specified transaction input.
 - `spentAmount`: Calculated as `Sum of all inputs with sourceAddress - Sum of all outputs with sourceAddress`. The value can be negative.
 - `blockTimestamp`: The **mediantime** of the block.
 
 ### Account-based chains (XRPL)
 
+#### Address Indication
+
 - `sourceAddressIndicator`: The [standard address hash](#standard-address-hash) of the address in question.
   - If the indicated address is not among the transaction signers and its balance was not decreased, the attestation request is rejected.
+
+#### Data Calculation
+
 - `spentAmount`: Difference between the balance of the address **after** and **before** the transaction. Can be negative.
 - `blockTimestamp`: The **close_time** of the ledger, converted to Unix time.
 
@@ -119,7 +128,7 @@ In particular, no summary is made for coinbase transactions.
 For XRPL, `sourceAddressIndicator` is [standardAddressHash](#standard-address-hash) of the indicated address.
 If the `sourceAddressIndicator` does not match any of the addresses who signed the transaction or whose balance was decreased by the transaction, the summary is not made.
 
-| Field           |                                                                                                   |
+| Field           | Description                                                                                       |
 | --------------- | ------------------------------------------------------------------------------------------------- |
 | `transactionId` | Hash of the transaction found in the field `hash`.                                                |
 | `sourceAddress` | Address whose [standardAddressHash](#standard-address-hash) matches the `sourceAddressIndicator`. |
@@ -141,6 +150,6 @@ If the `sourceAddressIndicator` does not match any of the addresses who signed t
 
 <Finality />
 
-## Contract interface
+## Contract Interface
 
-<IBalanceDecreasingTransaction />
+For the complete interface definition, see [`IBalanceDecreasingTransaction`](/fdc/reference/IBalanceDecreasingTransaction.mdx).

docs/fdc/attestation-types/confirmed-block-height-exists.mdx

@@ -6,16 +6,15 @@ sidebar_position: 3
 ---
 
 import Finality from "./_finality.mdx";
-import IConfirmedBlockHeightExists from "../reference/IConfirmedBlockHeightExists.mdx";
 
 Assertion whether a block with the specified `blockNumber` is **confirmed** with additional data to compute the **block production rate** within a given time window.
 
 ## Supported chains
 
-- `BTC` (Bitcoin)
-- `DOGE` (Dogecoin)
-- `XRP` (XRP Ledger)
-- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
+| Network Type | Supported Chains                                       |
+| ------------ | ------------------------------------------------------ |
+| **Mainnet**  | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
+| **Testnet**  | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`  |
 
 ## Request
 
@@ -54,6 +53,6 @@ For the `lowestUsedTimestamp` parameter, the value of `lowestQueryWindowBlockTim
 
 <Finality />
 
-## Contract interface
+## Contract Interface
 
-<IConfirmedBlockHeightExists />
+For the complete interface definition, see [`IConfirmedBlockHeightExists`](/fdc/reference/IConfirmedBlockHeightExists.mdx).

docs/fdc/attestation-types/evm-transaction.mdx

@@ -1,20 +1,18 @@
 ---
 title: EVMTransaction
-description: Information about an EVM transaction, including details on associated events if specified.
+description: Information about an EVM transaction including events.
 keywords: [fdc, oracle, flare-data-connector, flare-network]
 sidebar_position: 4
 ---
 
-import IEVMTransaction from "../reference/IEVMTransaction.mdx";
-
 Information about an Ethereum Virtual Machine (EVM) transaction, including details on associated events if specified.
 
 ## Supported chains
 
-- `ETH` (Ethereum)
-- `FLR` (Flare Mainnet)
-- `SGB` (Songbird Canary-Network)
-- Test networks: `testETH` (Ethereum Sepolia), `testFLR` (Flare Testnet Coston2), `testSGB` (Songbird Testnet Coston)
+| Network Type | Supported Chains                                                                                     |
+| ------------ | ---------------------------------------------------------------------------------------------------- |
+| **Mainnet**  | `ETH` (Ethereum), `FLR` (Flare Mainnet), `SGB` (Songbird Canary-Network)                             |
+| **Testnet**  | `testETH` (Ethereum Sepolia), `testFLR` (Flare Testnet Coston2), `testSGB` (Songbird Testnet Coston) |
 
 ## Request
 
@@ -76,6 +74,6 @@ Each `Event` struct represents a log entry similar to EVM event logs:
 
 :::
 
-## Contract interface
+## Contract Interface
 
-<IEVMTransaction />
+For the complete interface definition, see [`IEVMTransaction`](/fdc/reference/IEVMTransaction.mdx).

docs/fdc/attestation-types/json-api.mdx

@@ -1,42 +1,59 @@
 ---
 title: JsonApi
-description: An attestation request that fetches data from the given url and then edits the information with a jq transformation.
-keywords: [fdc, oracle, flare-data-connector, flare-network]
+description: Data retrieval from Web2 JSON APIs with JQ transformations.
+keywords: [fdc, oracle, flare-data-connector, flare-network, json, api, web2]
 sidebar_position: 1
 ---
 
-An attestation request that fetches data from the given url and then edits the information with a jq transformation.
+Data retrieval from **Web2 JSON APIs** with JQ transformations. This attestation type allows smart contracts to access and process external JSON data in a verifiable way.
+
+:::warning[Testnet Only]
+
+JsonApi attestation type is currently only available on Flare Testnet Coston2 and Songbird Testnet Coston.
+
+:::
 
 ## Supported sources
 
-- `WEB2`
-- test networks: `testWEB2`
+| Network Type | Sources                    |
+| ------------ | -------------------------- |
+| **Web2**     | `WEB2` (Web 2.0 JSON APIs) |
+| **Testnet**  | `testWEB2`                 |
 
 ## Request
 
-| Field           | Solidity type | Description                                              |
-| --------------- | ------------- | -------------------------------------------------------- |
-| `url`           | `string`      | URL of the data source.                                  |
-| `postprocessJq` | `string`      | JQ filter to postprocess the json received from the url. |
-| `abi_signature` | `string`      | ABI signature of struct for encoding.                    |
+| Field           | Solidity Type | Description                                                                      |
+| --------------- | ------------- | -------------------------------------------------------------------------------- |
+| `url`           | `string`      | URL of the JSON API endpoint to query.                                           |
+| `postprocessJq` | `string`      | JQ filter expression to transform the retrieved JSON data.                       |
+| `abi_signature` | `string`      | ABI signature defining the struct format for encoding the transformed JSON data. |
 
 ## Response
 
-| Field              | Solidity type | Description       |
-| ------------------ | ------------- | ----------------- |
-| `abi_encoded_data` | `bytes`       | ABI encoded data. |
+| Field              | Solidity Type | Description                                      |
+| ------------------ | ------------- | ------------------------------------------------ |
+| `abi_encoded_data` | `bytes`       | ABI-encoded data result after JQ transformation. |
+
+## Verification Process
+
+### 1. API Request
+
+The attestation service performs a GET request to the specified `url`.
 
-## Lowest Used Timestamp
+- If the request fails or returns non-JSON data, the attestation request is rejected.
+- The service validates that the response is valid JSON data.
 
-For `lowestUsedTimestamp`, `0xffffffffffffffff` ($2^{64}-1$ in hex) is used.
+### 2. JQ Transformation
 
-## Verification process
+The specified `postprocessJq` filter is applied to the retrieved JSON:
 
-Query the URL with GET method.
-If the query is unsuccessful or does not return a json, reject the request.
+- The JQ filter must be a valid JQ expression.
+- The filter's output must match the structure defined in `abi_signature`.
+- If the JQ transformation fails, the attestation request is rejected.
 
-Apply the jq filter specified in the request to the received json.
+### 3. ABI Encoding
 
-ABI encode the filtered json with the abi_signature provided in the request and return it as abi_encoded_data.
+The transformed data is ABI-encoded according to the provided `abi_signature`:
 
-`LowestUsedTimestamp` is unlimited.
+- The encoding must match the Solidity ABI specification.
+- The encoded bytes are returned in `abi_encoded_data`.

docs/fdc/attestation-types/payment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Payment
-description: Information about a transaction on an external chain that is classified as a native currency payment.
+description: Information about native token payments on an external chain.
 keywords: [fdc, oracle, flare-data-connector, flare-network]
 sidebar_position: 5
 ---
@@ -9,17 +9,16 @@ import StandardAddressHash from "./_standard_address_hash.mdx";
 import StandardPaymentReference from "./_standard_payment_reference.mdx";
 import TransactionSuccessStatus from "./_transaction_success_status.mdx";
 import Finality from "./_finality.mdx";
-import IPayment from "../reference/IPayment.mdx";
 
 Information about a transaction on an external chain that is classified as a **native currency payment**.
 Each supported blockchain specifies how a payment transaction should be formatted to be provable using this attestation type. These provable payments mimic traditional banking transactions where entity A sends a native currency to entity B, with an optional payment reference.
 
 ## Supported chains
 
-- `BTC` (Bitcoin)
-- `DOGE` (Dogecoin)
-- `XRP` (XRP Ledger)
-- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
+| Network Type | Supported Chains                                       |
+| ------------ | ------------------------------------------------------ |
+| **Mainnet**  | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
+| **Testnet**  | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`  |
 
 ## Request
 
@@ -110,12 +109,15 @@ Chain-specific explanations are provided in the sections that follow.
 
 The payment summary for Bitcoin and Dogecoin is derived using specified indices for a transaction input and output.
 
-- **Conditions**:
-  - If the specified input or output does not exist, or lacks an address (e.g., outputs using `OP_RETURN`), no summary is generated.
-  - Coinbase transactions are not summarized.
-- **Data Sources**:
-  - For Bitcoin, all transaction details are retrieved using the `getrawtransaction` endpoint (verbosity 2) and `getblock`. This requires a Bitcoin node version ≥ 25.0.
-  - For Dogecoin, since `getrawtransaction` with verbosity 2 is not supported, alternative methods must be used to access input transaction data.
+#### Conditions
+
+- If the specified input or output does not exist, or lacks an address (e.g., outputs using `OP_RETURN`), no summary is generated.
+- Coinbase transactions are not summarized.
+
+#### Data Sources
+
+- For Bitcoin, all transaction details are retrieved using the `getrawtransaction` endpoint (verbosity 2) and `getblock`. This requires a Bitcoin node version ≥ 25.0.
+- For Dogecoin, since `getrawtransaction` with verbosity 2 is not supported, alternative methods must be used to access input transaction data.
 
 | Field                      | Description                                                                                                                                     |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -133,12 +135,15 @@ The payment summary for Bitcoin and Dogecoin is derived using specified indices
 
 The payment summary on XRPL is applicable only for transactions of type `Payment`.
 
-- **Conditions**:
-  - Only `Payment` transactions are summarized; other transaction types are ignored.
-  - A successful payment has exactly one sender and at most one receiver. If unsuccessful, no receiver is recorded.
-- **Data Sources**:
-  - Transaction details are obtained via the [`tx`](https://xrpl.org/tx.html) method.
-  - Changes made by the transaction are recorded in the `meta` field (or `metaData` if fetched via the `ledger` method) under `AffectedNodes`. Balance changes are found within `ModifiedNodes`, by comparing `FinalFields` and `PreviousFields`.
+#### Conditions
+
+- Only `Payment` transactions are summarized; other transaction types are ignored.
+- A successful payment has exactly one sender and at most one receiver. If unsuccessful, no receiver is recorded.
+
+#### Data Sources
+
+- Transaction details are obtained via the [`tx`](https://xrpl.org/tx.html) method.
+- Changes made by the transaction are recorded in the `meta` field (or `metaData` if fetched via the `ledger` method) under `AffectedNodes`. Balance changes are found within `ModifiedNodes`, by comparing `FinalFields` and `PreviousFields`.
 
 | Field                      | Description                                                                                                                                |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -168,6 +173,6 @@ The payment summary on XRPL is applicable only for transactions of type `Payment
 
 <Finality />
 
-## Contract interface
+## Contract Interface
 
-<IPayment />
+For the complete interface definition, see [`IPayment`](/fdc/reference/IPayment.mdx).