Skip to content

Commit a5d0c71

Browse files
adg-flareLukaAvbreht
adg-flare
authored and
LukaAvbreht
committed
chore: Add repo information files, improve README.
1 parent 7a4ed7e commit a5d0c71

File tree

5 files changed

+145
-130
lines changed

5 files changed

+145
-130
lines changed

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @LukaAvbreht @adg-flare

‎CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- `Web2Json` attestation type support.
13+
14+
### Changed
15+
16+
- All `AddressValidity` attestation type requests will now result in `VALID` top-level response status.

‎CONTRIBUTING.md‎

Lines changed: 73 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -28,51 +28,97 @@ also welcome.
2828

2929
Prerequisites:
3030

31-
- Node.js 20+ (LTS recommended)
31+
- Node.js, as specified in the `.nvmrc` file. We recommend using `nvm` to manage versions.
3232
- Yarn 1.22.x
3333
- Docker Desktop (or Docker Engine) with Docker Compose v2 — required for tests
3434
- Git
3535

36-
Setup:
36+
Install the dependencies:
3737

38-
1. Install dependencies
38+
```bash
39+
$ yarn install
40+
```
41+
42+
### Configuration
3943

40-
```bash
41-
yarn install
42-
```
44+
Copy `.env.example` to `.env` and fill the required configuration parameters.
4345

44-
2. Build (TypeScript → dist)
4546

46-
```bash
47-
yarn build
48-
```
47+
### Running the app
4948

50-
3. Run locally
49+
To start app run:
5150

52-
- Development (watch mode):
51+
```bash
52+
# development
53+
$ yarn run start
5354

54-
```bash
55-
yarn start:dev
56-
```
55+
# watch mode
56+
$ yarn run start:dev
57+
```
5758

58-
- Standard start (no watch):
59+
### Testing with postgresql dump
5960

60-
```bash
61-
yarn start
62-
```
61+
Download the database instances from the following links and move them to `/e2e_tests/db/`:
6362

64-
- Production (after build):
63+
- [BTC Testnet Database](https://githubstatic.flare.center/db_btc_testnet) as `db_btc_testnet`
64+
- [BTC2 Testnet Database](https://githubstatic.flare.center/db_btc2_testnet) as `db_btc2_testnet`
65+
- [DOGE Testnet Database](https://githubstatic.flare.center/db_doge_testnet) as `db_doge_testnet`
66+
- [XRP Testnet Database](https://githubstatic.flare.center/db_xrp_testnet) as `db_xrp_testnet`
67+
- [XRP2 Testnet Database](https://githubstatic.flare.center/db_xrp2_testnet) as `db_xrp2_testnet`
6568

66-
```bash
67-
yarn start:prod
68-
```
69-
70-
## Linting and formatting
69+
or simply run:
70+
71+
```bash
72+
yarn test download
73+
```
74+
75+
Currently, all databases are from testnets.
76+
77+
#### Option 1: Running Tests Against a Database Instance
78+
79+
To run all tests across all sources or check code coverage, use the following commands:
80+
81+
```bash
82+
yarn test run
83+
yarn test coverage
84+
```
85+
86+
#### Option 2: Spinning Up a Database from a Dump and Persisting It
87+
88+
Depending on your source, create a database instance using the following command:
89+
90+
```bash
91+
yarn test make_db btc
92+
```
7193

72-
We use ESLint and Prettier.
94+
Once the database is up and running, you can start a local server and manually send requests. For this setup, set the
95+
following environment variables to your `.env` file:
7396

74-
Common commands:
97+
```bash
98+
# .env file
99+
DB_DATABASE=db
100+
DB_USERNAME=user
101+
DB_PASSWORD=pass
102+
DB_HOST=127.0.0.1
103+
DB_PORT=8080
104+
```
105+
106+
Additionally, set the appropriate values for `VERIFIER_TYPE` and `TESTNET`:
107+
108+
```bash
109+
VERIFIER_TYPE=btc
110+
TESTNET=true
111+
```
112+
113+
When you're finished, remember to stop the database server with:
114+
115+
```bash
116+
yarn test delete_db
117+
```
118+
119+
### Linting and formatting
75120

121+
We use ESLint and Prettier:
76122
- Check lint:
77123

78124
```bash
@@ -96,24 +142,6 @@ Common commands:
96142
```bash
97143
yarn format:fix
98144
```
99-
100-
## Testing
101-
102-
Tests are run with Mocha (TypeScript via ts-node) and require a Postgres Docker container that is managed by our test script.
103-
104-
Quick run (spins up DB, runs tests, tears down DB):
105-
106-
```bash
107-
# run all e2e + unit tests
108-
yarn test run
109-
```
110-
111-
Coverage:
112-
113-
```bash
114-
yarn test coverage
115-
# HTML and text reports under ./coverage
116-
```
117145
## Proposing Web2Json attestation type source changes
118146

119147
Community members can propose adding or removing supported Web2 API endpoints by updating the `Web2Json` source list at [src/config/web2/web2-json-sources.ts](src/config/web2/web2-json-sources.ts) and opening a pull request.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Flare Foundation
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 34 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,47 @@
1-
<p align="center">
2-
<a href="https://flare.network/" target="blank"><img src="https://flare.network/wp-content/uploads/Artboard-1-1.svg" width="400" height="300" alt="Flare Logo" /></a>
3-
</p>
1+
<!-- LOGO -->
2+
<div align="center">
3+
<a href="https://flare.network/" target="blank">
4+
<img src="https://content.flare.network/Flare-2.svg" width="300" alt="Flare Logo" />
5+
</a>
6+
<br />
7+
<a href="CONTRIBUTING.md">Contributing</a>
8+
·
9+
<a href="SECURITY.md">Security</a>
10+
·
11+
<a href="CHANGELOG.md">Changelog</a>
12+
</div>
413

5-
# Verifier server API implementation
14+
# FDC Attestation Verifier
615

7-
One can run the Verifier API service on three different sources:
16+
A microservice in the Flare Data Connector (FDC) suite responsible for verifying and executing attestation requests and
17+
providing ABI-encoded responses.
818

9-
- **BTC** / testBTC
10-
- **XRP** / testXRP
11-
- **DOGE** / testDOGE
19+
It can be configured to run one of the supported attestation type and source combination verifications.
1220

13-
For the API to function correctly, the service must be connected to the corresponding PostgreSQL database, which is populated using the appropriate indexing solution (e.g., BTC Indexer for BTC API Service).
21+
See documentation for more attestation type details: https://dev.flare.network/fdc/attestation-types/
1422

15-
## Local Installation
23+
## Blockchain data attestations
1624

17-
Make sure you're using the Node version specified in the `.nvmrc` file. We recommend using `nvm` to manage your local Node installations. Additionally, ensure that `yarn` is installed and enabled.
25+
Supported attestation types:
1826

19-
Install the dependencies
27+
- `AddressValidity`
28+
- `Payment`
29+
- `BalanceDecreasingTransaction`
30+
- `ReferencedPaymentNonexistence`
31+
- `ConfirmedBlockHeightExists`
2032

21-
```bash
22-
$ yarn install
23-
```
33+
Supported sources:
34+
- Mainnet: `BTC`, `DOGE`, `XRPL`
35+
- Testnet: `testBTC`, `testDOGE`, `testXRP`
2436

25-
## Configuration
37+
For these attestation types the verifier requires access to blockchain indexers writing to PostgreSQL backends (fully synced to the target network).
2638

27-
Copy `.env.example` to `.env` and fill the required configuration.
39+
## Web2 data attestations
2840

29-
## Running the app
41+
Supported attestation type: `Web2Json`
3042

31-
To start app run
43+
Supported sources:
44+
- Mainnet: [web2-json-sources.ts](src/config/web2/web2-json-sources.ts)
45+
- Testnet: [web2-json-test-sources.ts](src/config/web2/web2-json-test-sources.ts)
3246

33-
```bash
34-
# development
35-
$ yarn run start
36-
37-
# watch mode
38-
$ yarn run start:dev
39-
```
40-
41-
## Testing with postgresql dump
42-
43-
Download the database instances from the following links and move them to `/e2e_tests/db/`:
44-
45-
- [BTC Testnet Database](https://githubstatic.flare.center/db_btc_testnet) as `db_btc_testnet`
46-
- [BTC2 Testnet Database](https://githubstatic.flare.center/db_btc2_testnet) as `db_btc2_testnet`
47-
- [DOGE Testnet Database](https://githubstatic.flare.center/db_doge_testnet) as `db_doge_testnet`
48-
- [XRP Testnet Database](https://githubstatic.flare.center/db_xrp_testnet) as `db_xrp_testnet`
49-
- [XRP2 Testnet Database](https://githubstatic.flare.center/db_xrp2_testnet) as `db_xrp2_testnet`
50-
51-
or simply run
52-
53-
```bash
54-
yarn test download
55-
```
56-
57-
Currently, all databases are from testnets.
58-
59-
### Option 1: Running Tests Against a Database Instance
60-
61-
To run all tests across all sources or check code coverage, use the following commands:
62-
63-
```bash
64-
yarn test run
65-
yarn test coverage
66-
```
67-
68-
### Option 2: Spinning Up a Database from a Dump and Persisting It
69-
70-
Depending on your source, create a database instance using the following command:
71-
72-
```bash
73-
yarn test make_db btc
74-
```
75-
76-
Once the database is up and running, you can start a local server and manually send requests. For this setup, set the following environment variables to your `.env` file:
77-
78-
```bash
79-
# .env file
80-
DB_DATABASE=db
81-
DB_USERNAME=user
82-
DB_PASSWORD=pass
83-
DB_HOST=127.0.0.1
84-
DB_PORT=8080
85-
```
86-
87-
Additionally, set the appropriate values for `VERIFIER_TYPE` and `TESTNET`:
88-
89-
```bash
90-
VERIFIER_TYPE=btc
91-
TESTNET=true
92-
```
93-
94-
When you're finished, remember to stop the database server with:
95-
96-
```bash
97-
yarn test delete_db
98-
```
47+
Web2 data attestations fetch and transform JSON data from HTTP(S) endpoints using jq queries. Allowed endpoints are defined by the source configuration files above.

0 commit comments

Comments
 (0)