Skip to content

Commit 62b1a3f

Browse files
dineshpintodineshpinto
authored
fix(docs): add enhancement to the FDC guides (#578)
2 parents 0c757c8 + 80a6518 commit 62b1a3f

17 files changed

+1661
-196
lines changed

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

+7-8
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
11
---
22
title: AddressValidity
3-
description: Assertion whether a given string represents a valid address on an external blockchain.
3+
description: Validates if a string is a legitimate external blockchain address.
44
keywords: [fdc, oracle, flare-data-connector, flare-network]
55
sidebar_position: 1
66
---
77

88
import Addresses from "./_addresses.mdx";
9-
import IAddressValidity from "../reference/IAddressValidity.mdx";
109

1110
Assertion whether a given string represents a **valid address** on an external blockchain.
1211

1312
## Supported chains
1413

15-
- `BTC` (Bitcoin)
16-
- `DOGE` (Dogecoin)
17-
- `XRP` (XRP Ledger)
18-
- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
14+
| Network Type | Supported Chains |
15+
| ------------ | ------------------------------------------------------ |
16+
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
17+
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
1918

2019
## Request
2120

@@ -53,6 +52,6 @@ For the `lowestUsedTimestamp` parameter, the value `0xffffffffffffffff` (equival
5352

5453
<Addresses />
5554

56-
## Contract interface
55+
## Contract Interface
5756

58-
<IAddressValidity />
57+
For the complete interface definition, see [`IAddressValidity`](/fdc/reference/IAddressValidity.mdx).

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

+19-10
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: BalanceDecreasingTransaction
3-
description: Detects a transaction that either decreases the balance of a specified address.
3+
description: Detects a transaction decreasing the balance of an address.
44
keywords: [fdc, oracle, flare-data-connector, flare-network]
55
sidebar_position: 2
66
---
@@ -9,21 +9,20 @@ import Finality from "./_finality.mdx";
99
import StandardAddressHash from "./_standard_address_hash.mdx";
1010
import TransactionSuccessStatus from "./_transaction_success_status.mdx";
1111
import StandardPaymentReference from "./_standard_payment_reference.mdx";
12-
import IBalanceDecreasingTransaction from "../reference/IBalanceDecreasingTransaction.mdx";
1312

1413
Information describing a transaction that either **decreases the balance** for a specified address.
1514

16-
A transaction is considered “balance decreasing” for the specified address if:
15+
A transaction is considered "balance decreasing" for the specified address if:
1716

1817
1. The balance **after the transaction** is lower than **before**.
1918
2. The address is among the **signers** of the transaction (even if its balance is not reduced).
2019

2120
## Supported chains
2221

23-
- `BTC` (Bitcoin)
24-
- `DOGE` (Dogecoin)
25-
- `XRP` (XRP Ledger)
26-
- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
22+
| Network Type | Supported Chains |
23+
| ------------ | ------------------------------------------------------ |
24+
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
25+
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
2726

2827
## Request
2928

@@ -58,16 +57,26 @@ The verification process is chain-specific and can be computed with a [balance d
5857

5958
### UTXO chains (Bitcoin and Dogecoin)
6059

60+
#### Address Indication
61+
6162
- `sourceAddressIndicator`: Represents the index of the transaction input, formatted as a **0x-prefixed 32-byte string**.
6263
- If the specified input does not exist or lacks an associated address, the attestation request is rejected.
64+
65+
#### Data Calculation
66+
6367
- `sourceAddress`: Address associated with the specified transaction input.
6468
- `spentAmount`: Calculated as `Sum of all inputs with sourceAddress - Sum of all outputs with sourceAddress`. The value can be negative.
6569
- `blockTimestamp`: The **mediantime** of the block.
6670

6771
### Account-based chains (XRPL)
6872

73+
#### Address Indication
74+
6975
- `sourceAddressIndicator`: The [standard address hash](#standard-address-hash) of the address in question.
7076
- If the indicated address is not among the transaction signers and its balance was not decreased, the attestation request is rejected.
77+
78+
#### Data Calculation
79+
7180
- `spentAmount`: Difference between the balance of the address **after** and **before** the transaction. Can be negative.
7281
- `blockTimestamp`: The **close_time** of the ledger, converted to Unix time.
7382

@@ -119,7 +128,7 @@ In particular, no summary is made for coinbase transactions.
119128
For XRPL, `sourceAddressIndicator` is [standardAddressHash](#standard-address-hash) of the indicated address.
120129
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.
121130

122-
| Field | |
131+
| Field | Description |
123132
| --------------- | ------------------------------------------------------------------------------------------------- |
124133
| `transactionId` | Hash of the transaction found in the field `hash`. |
125134
| `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
141150

142151
<Finality />
143152

144-
## Contract interface
153+
## Contract Interface
145154

146-
<IBalanceDecreasingTransaction />
155+
For the complete interface definition, see [`IBalanceDecreasingTransaction`](/fdc/reference/IBalanceDecreasingTransaction.mdx).

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

+6-7
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,15 @@ sidebar_position: 3
66
---
77

88
import Finality from "./_finality.mdx";
9-
import IConfirmedBlockHeightExists from "../reference/IConfirmedBlockHeightExists.mdx";
109

1110
Assertion whether a block with the specified `blockNumber` is **confirmed** with additional data to compute the **block production rate** within a given time window.
1211

1312
## Supported chains
1413

15-
- `BTC` (Bitcoin)
16-
- `DOGE` (Dogecoin)
17-
- `XRP` (XRP Ledger)
18-
- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
14+
| Network Type | Supported Chains |
15+
| ------------ | ------------------------------------------------------ |
16+
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
17+
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
1918

2019
## Request
2120

@@ -54,6 +53,6 @@ For the `lowestUsedTimestamp` parameter, the value of `lowestQueryWindowBlockTim
5453

5554
<Finality />
5655

57-
## Contract interface
56+
## Contract Interface
5857

59-
<IConfirmedBlockHeightExists />
58+
For the complete interface definition, see [`IConfirmedBlockHeightExists`](/fdc/reference/IConfirmedBlockHeightExists.mdx).

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

+7-9
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
11
---
22
title: EVMTransaction
3-
description: Information about an EVM transaction, including details on associated events if specified.
3+
description: Information about an EVM transaction including events.
44
keywords: [fdc, oracle, flare-data-connector, flare-network]
55
sidebar_position: 4
66
---
77

8-
import IEVMTransaction from "../reference/IEVMTransaction.mdx";
9-
108
Information about an Ethereum Virtual Machine (EVM) transaction, including details on associated events if specified.
119

1210
## Supported chains
1311

14-
- `ETH` (Ethereum)
15-
- `FLR` (Flare Mainnet)
16-
- `SGB` (Songbird Canary-Network)
17-
- Test networks: `testETH` (Ethereum Sepolia), `testFLR` (Flare Testnet Coston2), `testSGB` (Songbird Testnet Coston)
12+
| Network Type | Supported Chains |
13+
| ------------ | ---------------------------------------------------------------------------------------------------- |
14+
| **Mainnet** | `ETH` (Ethereum), `FLR` (Flare Mainnet), `SGB` (Songbird Canary-Network) |
15+
| **Testnet** | `testETH` (Ethereum Sepolia), `testFLR` (Flare Testnet Coston2), `testSGB` (Songbird Testnet Coston) |
1816

1917
## Request
2018

@@ -76,6 +74,6 @@ Each `Event` struct represents a log entry similar to EVM event logs:
7674

7775
:::
7876

79-
## Contract interface
77+
## Contract Interface
8078

81-
<IEVMTransaction />
79+
For the complete interface definition, see [`IEVMTransaction`](/fdc/reference/IEVMTransaction.mdx).

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

+38-21
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,59 @@
11
---
22
title: JsonApi
3-
description: An attestation request that fetches data from the given url and then edits the information with a jq transformation.
4-
keywords: [fdc, oracle, flare-data-connector, flare-network]
3+
description: Data retrieval from Web2 JSON APIs with JQ transformations.
4+
keywords: [fdc, oracle, flare-data-connector, flare-network, json, api, web2]
55
sidebar_position: 1
66
---
77

8-
An attestation request that fetches data from the given url and then edits the information with a jq transformation.
8+
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.
9+
10+
:::warning[Testnet Only]
11+
12+
JsonApi attestation type is currently only available on Flare Testnet Coston2 and Songbird Testnet Coston.
13+
14+
:::
915

1016
## Supported sources
1117

12-
- `WEB2`
13-
- test networks: `testWEB2`
18+
| Network Type | Sources |
19+
| ------------ | -------------------------- |
20+
| **Web2** | `WEB2` (Web 2.0 JSON APIs) |
21+
| **Testnet** | `testWEB2` |
1422

1523
## Request
1624

17-
| Field | Solidity type | Description |
18-
| --------------- | ------------- | -------------------------------------------------------- |
19-
| `url` | `string` | URL of the data source. |
20-
| `postprocessJq` | `string` | JQ filter to postprocess the json received from the url. |
21-
| `abi_signature` | `string` | ABI signature of struct for encoding. |
25+
| Field | Solidity Type | Description |
26+
| --------------- | ------------- | -------------------------------------------------------------------------------- |
27+
| `url` | `string` | URL of the JSON API endpoint to query. |
28+
| `postprocessJq` | `string` | JQ filter expression to transform the retrieved JSON data. |
29+
| `abi_signature` | `string` | ABI signature defining the struct format for encoding the transformed JSON data. |
2230

2331
## Response
2432

25-
| Field | Solidity type | Description |
26-
| ------------------ | ------------- | ----------------- |
27-
| `abi_encoded_data` | `bytes` | ABI encoded data. |
33+
| Field | Solidity Type | Description |
34+
| ------------------ | ------------- | ------------------------------------------------ |
35+
| `abi_encoded_data` | `bytes` | ABI-encoded data result after JQ transformation. |
36+
37+
## Verification Process
38+
39+
### 1. API Request
40+
41+
The attestation service performs a GET request to the specified `url`.
2842

29-
## Lowest Used Timestamp
43+
- If the request fails or returns non-JSON data, the attestation request is rejected.
44+
- The service validates that the response is valid JSON data.
3045

31-
For `lowestUsedTimestamp`, `0xffffffffffffffff` ($2^{64}-1$ in hex) is used.
46+
### 2. JQ Transformation
3247

33-
## Verification process
48+
The specified `postprocessJq` filter is applied to the retrieved JSON:
3449

35-
Query the URL with GET method.
36-
If the query is unsuccessful or does not return a json, reject the request.
50+
- The JQ filter must be a valid JQ expression.
51+
- The filter's output must match the structure defined in `abi_signature`.
52+
- If the JQ transformation fails, the attestation request is rejected.
3753

38-
Apply the jq filter specified in the request to the received json.
54+
### 3. ABI Encoding
3955

40-
ABI encode the filtered json with the abi_signature provided in the request and return it as abi_encoded_data.
56+
The transformed data is ABI-encoded according to the provided `abi_signature`:
4157

42-
`LowestUsedTimestamp` is unlimited.
58+
- The encoding must match the Solidity ABI specification.
59+
- The encoded bytes are returned in `abi_encoded_data`.

‎docs/fdc/attestation-types/payment.mdx

+25-20
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Payment
3-
description: Information about a transaction on an external chain that is classified as a native currency payment.
3+
description: Information about native token payments on an external chain.
44
keywords: [fdc, oracle, flare-data-connector, flare-network]
55
sidebar_position: 5
66
---
@@ -9,17 +9,16 @@ import StandardAddressHash from "./_standard_address_hash.mdx";
99
import StandardPaymentReference from "./_standard_payment_reference.mdx";
1010
import TransactionSuccessStatus from "./_transaction_success_status.mdx";
1111
import Finality from "./_finality.mdx";
12-
import IPayment from "../reference/IPayment.mdx";
1312

1413
Information about a transaction on an external chain that is classified as a **native currency payment**.
1514
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.
1615

1716
## Supported chains
1817

19-
- `BTC` (Bitcoin)
20-
- `DOGE` (Dogecoin)
21-
- `XRP` (XRP Ledger)
22-
- Test networks: `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP`
18+
| Network Type | Supported Chains |
19+
| ------------ | ------------------------------------------------------ |
20+
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
21+
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
2322

2423
## Request
2524

@@ -110,12 +109,15 @@ Chain-specific explanations are provided in the sections that follow.
110109

111110
The payment summary for Bitcoin and Dogecoin is derived using specified indices for a transaction input and output.
112111

113-
- **Conditions**:
114-
- If the specified input or output does not exist, or lacks an address (e.g., outputs using `OP_RETURN`), no summary is generated.
115-
- Coinbase transactions are not summarized.
116-
- **Data Sources**:
117-
- For Bitcoin, all transaction details are retrieved using the `getrawtransaction` endpoint (verbosity 2) and `getblock`. This requires a Bitcoin node version ≥ 25.0.
118-
- For Dogecoin, since `getrawtransaction` with verbosity 2 is not supported, alternative methods must be used to access input transaction data.
112+
#### Conditions
113+
114+
- If the specified input or output does not exist, or lacks an address (e.g., outputs using `OP_RETURN`), no summary is generated.
115+
- Coinbase transactions are not summarized.
116+
117+
#### Data Sources
118+
119+
- For Bitcoin, all transaction details are retrieved using the `getrawtransaction` endpoint (verbosity 2) and `getblock`. This requires a Bitcoin node version ≥ 25.0.
120+
- For Dogecoin, since `getrawtransaction` with verbosity 2 is not supported, alternative methods must be used to access input transaction data.
119121

120122
| Field | Description |
121123
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -133,12 +135,15 @@ The payment summary for Bitcoin and Dogecoin is derived using specified indices
133135

134136
The payment summary on XRPL is applicable only for transactions of type `Payment`.
135137

136-
- **Conditions**:
137-
- Only `Payment` transactions are summarized; other transaction types are ignored.
138-
- A successful payment has exactly one sender and at most one receiver. If unsuccessful, no receiver is recorded.
139-
- **Data Sources**:
140-
- Transaction details are obtained via the [`tx`](https://xrpl.org/tx.html) method.
141-
- 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`.
138+
#### Conditions
139+
140+
- Only `Payment` transactions are summarized; other transaction types are ignored.
141+
- A successful payment has exactly one sender and at most one receiver. If unsuccessful, no receiver is recorded.
142+
143+
#### Data Sources
144+
145+
- Transaction details are obtained via the [`tx`](https://xrpl.org/tx.html) method.
146+
- 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`.
142147

143148
| Field | Description |
144149
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -168,6 +173,6 @@ The payment summary on XRPL is applicable only for transactions of type `Payment
168173

169174
<Finality />
170175

171-
## Contract interface
176+
## Contract Interface
172177

173-
<IPayment />
178+
For the complete interface definition, see [`IPayment`](/fdc/reference/IPayment.mdx).

0 commit comments

Comments
 (0)