Skip to content

Commit

Permalink
Merge remote-tracking branch 'bitbucket/release/2.0.2'
Browse files Browse the repository at this point in the history
  • Loading branch information
@Fletch153
Fletch153 committed Jun 9, 2022
2 parents 4b05ddf + 59359aa commit b296f88
Show file tree
Hide file tree
Showing 87 changed files with 4,464 additions and 1,533 deletions.
7 changes: 4 additions & 3 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ WORKDIR /home/gradle/src
RUN gradle assemble

# Stage 2 - the production environment
FROM openjdk:18-ea-4-oracle
FROM openjdk:18-oraclelinux8
WORKDIR /app
COPY --from=build /home/gradle/src/build/libs/*.jar /app/
ENTRYPOINT ["sh","-c","java -jar /app/headerSV-1.0.2.jar"]
COPY --from=build /home/gradle/src/app/build/libs/*.jar /app/
ENTRYPOINT ["sh","-c","java -jar /app/headersv-app-2.0.2.jar"]

146 changes: 36 additions & 110 deletions README.MD
View file
Original file line number Diff line number Diff line change
@@ -1,126 +1,52 @@
# HeaderSV Client
This is a lightweight header client for the BitcoinSV Blockchain. The client will connect to the BitcoinSV network and manage whitelists and blacklists internally. The application ensures that it is always connected to at least the minimum number of peers configured before synchronizing any blocks.
This is a lightweight client app for the BitcoinSV Blockchain. The App will connect to the BitcoinSV network and manage whitelists and blacklists internally.
The application ensures that it is always connected to at least the minimum number of peers configured before synchronizing any blocks.

A REST API is also provided by the application which will allow rapid lookups of chain and network state, as well as basic controls to control stored data.

The networks currently supported by the client are Mainnet, Testnet and STNnet. Additional networks can be added with ease.
The networks currently supported by the client are *Mainnet*, *Testnet* and *STNnet*. Additional networks can be added with ease.

### Dependencies
#### ** Note **
When building from source, HeaderSV is dependent on both BitcoinJ-SV and the Java Component Library (JCL), which are available on Maven Central under [/io/bitcoinsv/](https://repo.maven.apache.org/maven2/io/bitcoinsv/).
## HeaderSV Modules

#### Java
You will need Java SDK to build this application on your machine. Get the latest version of Java at:
https://www.java.com/en/download/help/index_installing.html
Since version 2.0, the *HeaderSV Client* is distributed in a multi-modular fashion. So while the pre-existing
functionality remains the same, now it's more flexible and easy to integrate into third party projects if needed to.
So, the *HeaderSV Client* is now a *Suite* of modules:

Each one of these modules can be consumed by an external *App*, and depending on the scenario you can use only the module you need

#### Gradle
![HeaderSV Suite](./headerSVModules.jpg)

HeaderSV uses Gradle as its build tool. You can find the latest version of Gradle at:
https://gradle.org/install/

### Installation
To build the application, navigate to the root folder and run `./gradlew clean build`.

Run the application using `./gradlew run`. The Mainnet will be synchronized by default. This can be changed by switching profiles in the application.properties file.
> **The previous versions of the *HeaderSV Client (v 1.x)* are equivalent now to the *headersv-app* module described below**
### Docker
You can build the docker file by either running `docker build -t headersv .` from the root directory. Or running `docker-compose build`. Once built, you can run by either
`docker run headersv` or `docker-compose up`. Note: if you're not using docker compose, you'll also need to expose the port and mount a volume to expose the API and persist state.
---

## Verifying
To check your client application is serving REST API calls once running, open a browser at `http://localhost:8001/api/v1/chain/tips` (default port is specified in the `docker-compose` file)
* [**headerSV-app**](app/README.MD): This is equivalent to the *HeaderSV Client v.1.x*. It is a standalone application that can be deployed
and it also provides a *REST API* we can use to retrieve information about the Chain.

**If you are just upgrading from previous versions of *HeaderSV Client* and want things unchanged, this is the right module.**

---

## Configuration
The application has 4 default profiles:
- `bsv-mainnet`
- `bsv-testnet`
- `bsv-stnnet`
- `bsv-regtest`
* [**headerSV-rest**](rest/README.MD): This module is a Java library (JAR) that provides the REST API mentioned above as a separate layer that
you can add to your pre-existing Application.

**If you already have an application and want to add *HeaderSV capabilities*
to it rather than deploy a separate app, this is the right module.**

---

You can switch between profiles by altering the value `spring.profiles.active=bsv-xxx` in `resources/application.yml`. Profiles can be amended to
alter the values such as `minPeers` and `maxPeers`.
* [**headerSV-rest-client**](rest-client/README.MD): This module is a Java Library (JAR) that provides a client for the *REST API*.

**If you only want to
*consume* the info produced from *HeaderSV* which is running in a different machine, this is right module.**

---

###Docker
Profiles can also be amended by overriding using environment variables, such as those in the `docker-compose` file.
* [**headerSV-core**](core/README.MD): This module is a Java Library that implements the *core* functionality of *HeaderSV*: It connects to the
network, synchronizes with the Chain and provides an API (not REST) that can be used to retrieve information from it.

**If you
want to synchronize with the chain and get updated in real-time about changes in it, this is the right module.**

## API | V1

### Chain

#### Query Chain Tips
Returns the latest headers for the tip of the chain and any forks
```
/api/v1/chain/tips
```
Returns the the specified header for the tip of the chain and any forks

#### Prune Fork
Prunes a specified fork
```
/api/v1/chain/tips/prune/{hash}
```
ID | TYPE | Description |
---|------|-------------|
hash | STRING | The Header hash

#### Query Headers
Retrieves the header with the given hash
```
/api/v1/chain/header/{hash}
```
The Accept type: ```application/octet-stream``` can be provided in the request header to return the headers raw bytes.

#### Query Headers By Height (batched)
Retrieves the header with the given hash
```
/api/v1/chain/header/byHeight?height=<start_height>&count=<count>
```
The Accept type: ```application/octet-stream``` can be provided in the request header to return the headers as a
stream of raw bytes.

The query parameter: height is required. The count of headers requested is optional (default = 1)

#### Query Headers State
Retrieves the header with the given hash along with it's state relative to the chain
```
/api/v1/chain/header/state/{hash}
```
ID | TYPE | Description |
---|------|-------------|
hash | STRING | The Header hash

#### Response
Returns a list of block headers and their state if specified.
```
{
"header": {
"hash": "00000000dfd5d65c9d8561b4b8f60a63018fe3933ecb131fb37f905f87da951a",
"version": 1,
"prevBlockHash": "00000000a1496d802a4a4074590ec34074b76a8ea6b81c1c9ad4192d3c2ea226",
"merkleRoot": "10f072e631081ad6bcddeabb90bc34d787fe7d7116fe0298ff26c50c5e21bfea",
"creationTimestamp": 1233046715,
"difficultyTarget": 486604799,
"nonce": 2999858432,
"transactionCount": 0,
"work": 4295032833
},
"state": "STALE",
"chainWork": 65537,
"height": 2000,
"confirmations": 4000
}
```

ID | TYPE | VALUES |
---|------|-------------|
state | ENUM | LONGEST_CHAIN, ORPHAN or STALE

#### Query Network
Returns a list of peers that are connected to the application
```
/api/v1/network/peers
```
Returns the number of peers connected to the application
```
/api/v1/network/peers/count
```
0 LICENSE → app/LICENSE
View file
File renamed without changes.
134 changes: 134 additions & 0 deletions app/README.MD
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
# HeaderSV-App module

The *HeaderSV-app* module is the highest-level module in the HeaderSV Suite. It is a standalone application that
connects to the blockchain, synchronizes the Block Headers while running also validations on them, and making sure that it's
always connected to enough Peers.

> The *headerSV-app* module provides the same functionality as the **HeaderSV Client** in previous versions (1.*)
A REST API is also provided by the application which will allow rapid lookups of chain and network state, as well as basic controls to control stored data.

The networks currently supported by the client are **Mainnet**, **Testnet** and **STNnet**. Additional networks can be added with ease.

### Dependencies
#### ** Note **
When building from source, HeaderSV-app is dependent on both BitcoinJ-SV and the Java Component Library (JCL), which are available on Maven Central under [/io/bitcoinsv/](https://repo.maven.apache.org/maven2/io/bitcoinsv/).

#### Java
You will need Java SDK to build this application on your machine. Get the latest version of Java at:
https://www.java.com/en/download/help/index_installing.html

#### Gradle

HeaderSV uses Gradle as its build tool. You can find the latest version of Gradle at:
https://gradle.org/install/

### Installation
To build the application, navigate to the "*/app*" folder and run `gradlew clean build`.

Run the application using `gradlew run`. The *Mainnet* will be synchronized by default. This can be changed by switching profiles in the ```application.properties``` file.

### Docker
You can build the docker file by either running `docker build -t headersv-app .` from the root directory. Or running `docker-compose build`. Once built, you can run by either
`docker run headersv-app` or `docker-compose up`. Note: if you're not using docker compose, you'll also need to expose the port and mount a volume to expose the API and persist state.

## Verifying
To check your client application is serving REST API calls once running, open a browser at `http://localhost:8001/api/v1/chain/tips` (default port is specified in the `docker-compose` file)

## Configuration
The application has 4 default profiles:

- `bsv-mainnet`
- `bsv-testnet`
- `bsv-stnnet`
- `bsv-regtest`

You can switch between profiles by altering the value `spring.profiles.active=bsv-xxx` in `resources/application.yml`. Profiles can be amended to
alter the values such as `minPeers` and `maxPeers`.

###Docker
Profiles can also be amended by overriding using environment variables, such as those in the `docker-compose` file.

## API | V1

### Chain

#### Query Chain Tips
Returns the latest headers for the tip of the chain and any forks
```
/api/v1/chain/tips
```
Returns the the specified header for the tip of the chain and any forks

#### Prune Fork
Prunes a specified fork
```
/api/v1/chain/tips/prune/{hash}
```

ID | TYPE | Description |
---|------|-------------|
hash | STRING | The Header hash

#### Query Headers
Retrieves the header with the given hash
```
/api/v1/chain/header/{hash}
```
The content type: ```application/octet-stream``` can be provided in the requst header to return the headers raw bytes.

#### Query Headers By Height (batched)
Retrieves the header with the given hash
```
/api/v1/chain/header/byHeight?height=<start_height>&count=<count>
```
The Accept type: ```application/octet-stream``` can be provided in the requst header to return the headers as a
stream of raw bytes.

The query parameter: height is required. The count of headers requested is optional (default = 1)

#### Query Headers State
Retrieves the header with the given hash along with it's state relative to the chain
```
/api/v1/chain/header/state/{hash}
```

ID | TYPE | Description |
---|------|-------------|
hash | STRING | The Header hash

#### Response
Returns a list of block headers and their state if specified.
```
{
"header": {
"hash": "00000000dfd5d65c9d8561b4b8f60a63018fe3933ecb131fb37f905f87da951a",
"version": 1,
"prevBlockHash": "00000000a1496d802a4a4074590ec34074b76a8ea6b81c1c9ad4192d3c2ea226",
"merkleRoot": "10f072e631081ad6bcddeabb90bc34d787fe7d7116fe0298ff26c50c5e21bfea",
"creationTimestamp": 1233046715,
"difficultyTarget": 486604799,
"nonce": 2999858432,
"transactionCount": 0,
"work": 4295032833
},
"state": "STALE",
"chainWork": 65537,
"height": 2000,
"confirmations": 4000
}
```

ID | TYPE | VALUES |
---|------|-------------|
state | ENUM | LONGEST_CHAIN, ORPHAN or STALE

#### Query Network
Returns a list of peers that are connected to the application
```
/api/v1/network/peers
```
Returns the number of peers connected to the application
```
/api/v1/network/peers/count
```
62 changes: 62 additions & 0 deletions app/build.gradle
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
plugins {
id 'org.springframework.boot'
id 'io.spring.dependency-management'
id 'idea'
id 'java'
id 'application'
id 'maven-publish'
}
/****************************************
* Local Configuration
****************************************/

group = "$hsvGroup"
version = "$hsvVersion"

def artifactName = "$hsvArtifactName"


repositories {
mavenCentral()
mavenLocal()
}

dependencies {

// HeaderSV Modules
implementation(project(":rest"))
implementation(project(":core"))

// logging
implementation 'org.slf4j:slf4j-api:1.7.26'

// JUnit
testImplementation 'org.junit.jupiter:junit-jupiter-api'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'

// logback
testImplementation "ch.qos.logback:logback-classic"

// Spring
implementation 'org.springframework.boot:spring-boot-starter-web'

}

mainClassName = "io.bitcoinsv.headerSV.app.HeaderSVApplication"
bootJar {
enabled = true
archiveFileName = "${artifactName}-${version}.jar"
metaInf {
from "${project.rootDir}/LICENSE"
}
}



jar {
enabled = false
}

test {
useJUnitPlatform()
}
1 change: 1 addition & 0 deletions app/gradle.properties
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
hsvArtifactName=headersv-app
Loading

0 comments on commit b296f88

Please sign in to comment.