Skip to content

Commit 16d2224

Browse files
nikerzetic-aflabsnikerzetic-aflabs
committed
fix(docs): Solidity references aligned with periphery v0.1.41 + 6 stubs
1 parent fcfe889 commit 16d2224

20 files changed

Lines changed: 550 additions & 728 deletions

‎docs/fassets/reference/IAgentPing.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: IAgentPing
3+
sidebar_position: 9
4+
description: On-chain liveness ping/response between users and FAssets agent bots.
5+
---
6+
7+
:::caution Preview
8+
This page is a hand-written stub extracted directly from the periphery release (`@flarenetwork/flare-periphery-contracts` v0.1.41) while the auto-generated reference catches up.
9+
:::
10+
11+
`IAgentPing` exposes a simple ping/response protocol for verifying that an FAssets agent's off-chain bot is alive.
12+
Users (or anyone) call `agentPing(agentVault, query)` to emit a `AgentPing` event; the bot listens for these events and replies with `agentPingResponse(agentVault, query, response)`, which emits an `AgentPingResponse` event identifying the owner address.
13+
14+
Sourced from `IAgentPing.sol` on [GitHub](https://github.com/flare-foundation/fassets/blob/main/contracts/userInterfaces/IAgentPing.sol).
15+
16+
## Functions
17+
18+
### agentPing
19+
20+
```solidity
21+
function agentPing(address _agentVault, uint256 _query) external;
22+
```
23+
24+
Emits an `AgentPing` event addressed at `_agentVault`.
25+
`_query` is an off-chain-defined identifier that helps the bot decide which kind of response is required (and whether the request is worth responding to at all).
26+
27+
### agentPingResponse
28+
29+
```solidity
30+
function agentPingResponse(
31+
address _agentVault,
32+
uint256 _query,
33+
string calldata _response
34+
) external;
35+
```
36+
37+
Called by the agent owner address in response to an `AgentPing`.
38+
Emits `AgentPingResponse(agentVault, owner, query, response)`.
39+
40+
## Events
41+
42+
### AgentPing
43+
44+
```solidity
45+
event AgentPing(address indexed agentVault, address indexed sender, uint256 query);
46+
```
47+
48+
### AgentPingResponse
49+
50+
```solidity
51+
event AgentPingResponse(address indexed agentVault, address indexed owner, uint256 query, string response);
52+
```

‎docs/fassets/reference/ICoreVaultClient.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: ICoreVaultClient
3+
sidebar_position: 8
4+
description: Agent-facing interface for transferring backing assets into and out of the FAssets core vault.
5+
---
6+
7+
:::caution Preview
8+
This page is a hand-written stub extracted directly from the periphery release (`@flarenetwork/flare-periphery-contracts` v0.1.41) while the auto-generated reference catches up.
9+
Function signatures and events may change between periphery releases — cross-check against the source before pinning your contract code.
10+
:::
11+
12+
`ICoreVaultClient` is the agent-facing surface of the FAssets **core vault** subsystem.
13+
Agents transfer backing into the core vault to free up capital, and request returns when they need to redeem.
14+
Direct minting (FAssets minted without an XRPL payment from the user) and direct redemptions also flow through this client.
15+
16+
Sourced from `ICoreVaultClient.sol` on [GitHub](https://github.com/flare-foundation/fassets/blob/main/contracts/userInterfaces/ICoreVaultClient.sol).
17+
18+
## Workflows
19+
20+
The interface groups three lifecycle flows:
21+
22+
1. **Transfer to core vault** — `transferToCoreVault`, with `TransferToCoreVaultStarted` → `TransferToCoreVaultSuccessful` (or `TransferToCoreVaultDefaulted`) events.
23+
2. **Return from core vault** — `requestReturnFromCoreVault` → `confirmReturnFromCoreVault`, with the corresponding `ReturnFromCoreVault*` events.
24+
3. **Core-vault redemption** — `redeemFromCoreVault`, emitting `CoreVaultRedemptionRequested`.
25+
26+
## Events
27+
28+
A non-exhaustive list of the events exposed by `ICoreVaultClient` (consult the source for the full list and field semantics):
29+
30+
- `TransferToCoreVaultStarted(address agentVault, uint256 transferRedemptionRequestId, uint256 valueUBA)`
31+
- `TransferToCoreVaultDefaulted(address agentVault, uint256 transferRedemptionRequestId, uint256 remintedUBA)`
32+
- `TransferToCoreVaultSuccessful(address agentVault, uint256 transferRedemptionRequestId, uint256 valueUBA)`
33+
- `ReturnFromCoreVaultRequested(address agentVault, uint256 requestId, bytes32 paymentReference, uint256 valueUBA)`
34+
- `ReturnFromCoreVaultCancelled(address agentVault, uint256 requestId)`
35+
- `ReturnFromCoreVaultConfirmed(address agentVault, uint256 requestId, uint256 receivedUnderlyingUBA, uint256 remintedUBA)`
36+
- `CoreVaultRedemptionRequested(address redeemer, string paymentAddress, bytes32 paymentReference, uint256 valueUBA, uint256 feeUBA)`
37+
38+
See the linked source for the full set of functions and accompanying NatSpec.

‎docs/fassets/reference/IFAsset.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: IFAsset
3+
sidebar_position: 7
4+
description: ERC-20 plus FAsset-specific metadata for FXRP / FBTC / FDOGE / FLTC tokens.
5+
---
6+
7+
:::caution Preview
8+
This page is a hand-written stub extracted directly from the periphery release (`@flarenetwork/flare-periphery-contracts` v0.1.41) while the auto-generated reference catches up.
9+
:::
10+
11+
`IFAsset` is the ERC-20 surface of an FAsset token (FXRP, FBTC, FDOGE, FLTC, ...) with three extra accessors that expose the underlying asset's identity and the `IAssetManager` bound to this FAsset.
12+
It extends OpenZeppelin's [`IERC20`](https://docs.openzeppelin.com/contracts/5.x/api/token/erc20#IERC20) and [`IERC20Metadata`](https://docs.openzeppelin.com/contracts/5.x/api/token/erc20#IERC20Metadata).
13+
14+
Sourced from `IFAsset.sol` on [GitHub](https://github.com/flare-foundation/fassets/blob/main/contracts/userInterfaces/IFAsset.sol).
15+
16+
## Functions
17+
18+
### assetName
19+
20+
The name of the underlying asset (for example, `"XRP"` for FXRP).
21+
22+
```solidity
23+
function assetName() external view returns (string memory);
24+
```
25+
26+
### assetSymbol
27+
28+
The symbol of the underlying asset (for example, `"XRP"`).
29+
30+
```solidity
31+
function assetSymbol() external view returns (string memory);
32+
```
33+
34+
### assetManager
35+
36+
The address of the [`IAssetManager`](/fassets/reference/IAssetManager) instance that controls minting and redemption for this FAsset.
37+
FAssets and asset managers are in 1:1 correspondence.
38+
39+
```solidity
40+
function assetManager() external view returns (address);
41+
```

‎docs/fdc/reference/IAddressValidity.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,15 @@ Sourced from `IAddressValidity.sol` on [GitHub](https://github.com/flare-foundat
1414

1515
## Overview
1616

17-
The IAddressValidity interface enables smart contracts to verify if a given string is a valid address on supported external blockchains. This attestation provides standardized representations of addresses across different chains, facilitating cross-chain operations within the Flare ecosystem.
17+
The IAddressValidity interface enables smart contracts to verify if a given string is a valid address on supported external blockchains.
18+
This attestation provides standardized representations of addresses across different chains, facilitating cross-chain operations within the Flare ecosystem.
1819

1920
## Supported Chains
2021

2122
| Network Type | Supported Chains |
2223
| ------------ | ------------------------------------------------------ |
2324
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
24-
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
25+
| **Testnet** | `testBTC` (Bitcoin Testnet 4), `testDOGE`, `testXRP` |
2526

2627
## Structs
2728

‎docs/fdc/reference/IBalanceDecreasingTransaction.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ This attestation type is particularly useful for detecting when a party has viol
2626
| Network Type | Supported Chains |
2727
| ------------ | ------------------------------------------------------ |
2828
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
29-
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
29+
| **Testnet** | `testBTC` (Bitcoin Testnet 4), `testDOGE`, `testXRP` |
3030

3131
## Chain-Specific Implementation Details
3232

‎docs/fdc/reference/IConfirmedBlockHeightExists.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,15 @@ Sourced from `IConfirmedBlockHeightExists.sol` on [GitHub](https://github.com/fl
1414

1515
## Overview
1616

17-
The IConfirmedBlockHeightExists interface allows smart contracts to verify that a specific block number exists and has reached the required confirmation threshold on an external blockchain. Additionally, it provides data to calculate block production rates over a specified time window, which can be useful for estimating transaction finality times or implementing time-dependent logic.
17+
The IConfirmedBlockHeightExists interface allows smart contracts to verify that a specific block number exists and has reached the required confirmation threshold on an external blockchain.
18+
Additionally, it provides data to calculate block production rates over a specified time window, which can be useful for estimating transaction finality times or implementing time-dependent logic.
1819

1920
## Supported Chains
2021

2122
| Network Type | Supported Chains |
2223
| ------------ | ------------------------------------------------------ |
2324
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
24-
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
25+
| **Testnet** | `testBTC` (Bitcoin Testnet 4), `testDOGE`, `testXRP` |
2526

2627
## Chain-Specific Confirmation Requirements
2728

‎docs/fdc/reference/IFdcVerification.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Sourced from `IFdcVerification.sol` on [GitHub](https://github.com/flare-foundat
1414

1515
## Overview
1616

17-
The IFdcVerification interface provides methods to verify different types of attestations from the Flare Data Connector. Smart contracts can use these verification functions to validate proofs provided by the FDC, ensuring the authenticity and integrity of the external data being used.
17+
The IFdcVerification interface provides methods to verify different types of attestations from the Flare Data Connector.
18+
Smart contracts can use these verification functions to validate proofs provided by the FDC, ensuring the authenticity and integrity of the external data being used.
1819

1920
## Verification Functions
2021

@@ -140,6 +141,45 @@ function verifyReferencedPaymentNonexistence(
140141

141142
- `_proved`: Boolean indicating if the proof is valid
142143

144+
### verifyWeb2Json
145+
146+
Verifies a proof for a Web2Json attestation (FDC-fetched HTTP response post-processed through JQ).
147+
148+
```solidity
149+
function verifyWeb2Json(
150+
struct IWeb2Json.Proof _proof
151+
) external view returns (
152+
bool _proved
153+
);
154+
```
155+
156+
**Parameters**
157+
158+
- `_proof`: The Web2Json proof structure
159+
160+
**Returns**
161+
162+
- `_proved`: Boolean indicating if the proof is valid
163+
164+
## Metadata accessors
165+
166+
### fdcProtocolId
167+
168+
Returns the FDC protocol id used as the `protocolId` argument when querying `IRelay.isFinalized(protocolId, votingRoundId)`.
169+
Read this at runtime instead of hard-coding a literal — the value can change between network releases.
170+
171+
```solidity
172+
function fdcProtocolId() external view returns (uint8 _fdcProtocolId);
173+
```
174+
175+
### relay
176+
177+
Returns the `IRelay` contract address bound to this `IFdcVerification` deployment.
178+
179+
```solidity
180+
function relay() external view returns (IRelay);
181+
```
182+
143183
## Usage Example
144184

145185
<CodeBlock language="solidity" title="AddressSolidity.sol">

‎docs/fdc/reference/IJsonApi.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: IJsonApi
3+
sidebar_position: 11
4+
description: Legacy JsonApi attestation type — superseded by Web2Json.
5+
unlisted: true
6+
---
7+
8+
:::caution Deprecated
9+
The `JsonApi` attestation type is the predecessor of [`Web2Json`](/fdc/reference/IWeb2Json) and is retained in periphery v0.1.41 for backward compatibility only.
10+
**New integrations should use `Web2Json`** — it supports the same URL/jq/abi-signature contract plus headers, query parameters, and an explicit HTTP method.
11+
The field names below intentionally use the legacy `postprocessJq` / `abi_signature` / `abi_encoded_data` snake_case form.
12+
:::
13+
14+
Sourced from `IJsonApi.sol` on [GitHub](https://github.com/flare-foundation/flare-smart-contracts-v2/blob/main/contracts/userInterfaces/IJsonApi.sol).
15+
16+
## Structs
17+
18+
### Request
19+
20+
```solidity
21+
struct Request {
22+
bytes32 attestationType;
23+
bytes32 sourceId;
24+
bytes32 messageIntegrityCode;
25+
RequestBody requestBody;
26+
}
27+
```
28+
29+
### Response
30+
31+
```solidity
32+
struct Response {
33+
bytes32 attestationType;
34+
bytes32 sourceId;
35+
uint64 votingRound;
36+
uint64 lowestUsedTimestamp;
37+
RequestBody requestBody;
38+
ResponseBody responseBody;
39+
}
40+
```
41+
42+
### Proof
43+
44+
```solidity
45+
struct Proof {
46+
bytes32[] merkleProof;
47+
Response data;
48+
}
49+
```
50+
51+
### RequestBody
52+
53+
```solidity
54+
struct RequestBody {
55+
string url;
56+
string postprocessJq;
57+
string abi_signature;
58+
}
59+
```
60+
61+
### ResponseBody
62+
63+
```solidity
64+
struct ResponseBody {
65+
bytes abi_encoded_data;
66+
}
67+
```

‎docs/fdc/reference/IPayment.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,16 @@ Sourced from `IPayment.sol` on [GitHub](https://github.com/flare-foundation/flar
1414

1515
## Overview
1616

17-
The IPayment interface enables smart contracts on Flare networks to access and verify native currency payment transactions from external blockchains. It provides a standardized way to prove that payments have occurred between entities, similar to traditional banking transfers, with support for payment references. This attestation type handles the different transaction models across various blockchains, offering a unified interface for payment verification.
17+
The IPayment interface enables smart contracts on Flare networks to access and verify native currency payment transactions from external blockchains.
18+
It provides a standardized way to prove that payments have occurred between entities, similar to traditional banking transfers, with support for payment references.
19+
This attestation type handles the different transaction models across various blockchains, offering a unified interface for payment verification.
1820

1921
## Supported Chains
2022

2123
| Network Type | Supported Chains |
2224
| ------------ | ------------------------------------------------------ |
2325
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
24-
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
26+
| **Testnet** | `testBTC` (Bitcoin Testnet 4), `testDOGE`, `testXRP` |
2527

2628
## Chain-Specific Implementation Details
2729

‎docs/fdc/reference/IReferencedPaymentNonexistence.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,15 @@ Sourced from `IReferencedPaymentNonexistence.sol` on [GitHub](https://github.com
1414

1515
## Overview
1616

17-
The IReferencedPaymentNonexistence interface enables smart contracts on Flare networks to verify the absence of specific payment transactions on external blockchains. This type of attestation is particularly useful for conditional agreements where the absence of a payment by a deadline triggers consequences, such as liquidating collateral or executing penalties in cross-chain financial arrangements.
17+
The IReferencedPaymentNonexistence interface enables smart contracts on Flare networks to verify the absence of specific payment transactions on external blockchains.
18+
This type of attestation is particularly useful for conditional agreements where the absence of a payment by a deadline triggers consequences, such as liquidating collateral or executing penalties in cross-chain financial arrangements.
1819

1920
## Supported Chains
2021

2122
| Network Type | Supported Chains |
2223
| ------------ | ------------------------------------------------------ |
2324
| **Mainnet** | `BTC` (Bitcoin), `DOGE` (Dogecoin), `XRP` (XRP Ledger) |
24-
| **Testnet** | `testBTC` (Bitcoin Testnet v3), `testDOGE`, `testXRP` |
25+
| **Testnet** | `testBTC` (Bitcoin Testnet 4), `testDOGE`, `testXRP` |
2526

2627
## Chain-Specific Verification Criteria
2728

0 commit comments

Comments
 (0)