README.md

Validation Oracle Libs

This project contains libraries for communicating with the validation oracle (VO) smart contract.

Status

Artifacts

Client

Utilities

Compatibility

Kotlin Client	VO Smart Contract
TBA	TBA

Using the VOClient

Creating an VOClient instance

To establish an VOClient, first, create a PbClient. The PbClient comes pre-bundled with the client artifact, when imported. The PbClient controls which provenance instance the application is communicating with, and, importantly, the provenance instance to which the Validation Oracle smart contract is deployed. Then, with the PbClient instance, create your VOClient.

Example

import io.provenance.client.grpc.GasEstimationMethod
import io.provenance.client.grpc.PbClient
import java.net.URI
import tech.figure.validationoracle.client.client.base.VOClient
import tech.figure.validationoracle.client.client.base.ContractIdentifier

class SampleConfiguration {
  fun buildClients() {
    // First, you'll need a PbClient
    val pbClient = PbClient(
      // chain-local for a local environment, pio-testnet-1 for the test environment
      chainId = "my-chain-id",
      // http://localhost:9090 for local, or some non-local channel uri
      channelUri = URI("my-channel-uri"),
      // or GasEstimationMethod.COSMOS_SIMULATION
      gasEstimationMethod = GasEstimationMethod.MSG_FEE_CALCULATION
    )
    // Then, the VOClient will know where to look for the validation oracle smart contract
    // The root interfaces are exposed if you want to create your own implementation, but a default implementation can
    // easily be built simply by using the default function in the companion object of the VOClient interface:
    val voClient = VOClient.getDefault(
      // validationoracle.pb for local, or some other contract name. 
      // Alternatively, if the contract's bech32 address is directly known, you can use ContractIdentifier.Address("mycontractaddressbech32")
      contractIdentifier = ContractIdentifier.Name("mycontractname"),
      pbClient = pbClient,
      // This is the default and can be omitted, but it exists for if you'd like to provide your own Jackson ObjectMapper instance
      objectMapper = VOObjectMapperUtil.OBJECT_MAPPER,
    )
  }
}

Testing

This repository includes integration tests which tests the library against a Provenance Docker container that has an instantiated VO smart contract. By running the Gradle test task, Testcontainers will automatically set up the necessary containers for the tests. The tests will need some time to set up, but can be sped up by allocating more CPU and RAM to the Docker environment.

Manual Local Environment

You can manually stand up the integration test environment using

# From the root of this repository
docker compose -f client/src/test/resources/docker-compose.yml up -d -V --force-recreate

This command can be supplemented with certain environment variables to override the environment's defaults, e.g.

# From the root of this repository
RUST_OPTIMIZER_VERSION=0.12.10 docker compose -f client/src/test/resources/docker-compose.yml up -d

To shut down and reset the environment, run

# From the root of this repository
docker compose -f client/src/test/resources/docker-compose.yml down -v