LiveScore Oracle

Truffle Box for LiveScore API generated using TruSource.

The project includes an example contract that implements the LiveScore OracleAPI, demonstrating its use along with a local listening server. You are encouraged to replace Example.sol with you own contract that inherits OracleAPI.sol, uses its operations and implements the trusource_callback.

For more details, please see the docs.

Requirements

• Node.js v8.9.4 (required) / v10.5.0+ (recommended)

Installation

Ensure you are in a new and empty directory.

1. Run the unbox command via npx. This will install all necessary dependencies.

   npx truffle unbox TruSource/ApiDojo-LiveScore

2. Alternatively, you can install Truffle globally and run the unbox command.

   npm i -g truffle
   truffle unbox TruSource/ApiDojo-LiveScore

3. You could also download this repository and install the dependencies yourself.

   git clone https://github.com/TruSource/ApiDojo-LiveScore
   cd ApiDojo-LiveScore
   npm i

Development

Local

1. Start an Ethereum client. We will use ganache-cli.

   npx ganache-cli

   Note: the client needs to support WebSockets (do not use truffle develop for this reason).

   For other options, see Truffle - Choosing an Ethereum client.

2. Migrate the smart contracts.

   // in a 2nd terminal (i.e. not in the eth client terminal)
   truffle migrate

3. Start the TruSource local server. It will listen for events, fetch and return data to requesting contracts.

   // in a 3rd terminal
   npm start

4. Using the provided Truffle script ./server/calls.js, call functions in Example.sol. This will execute a set of contracts calls, testing each operation with provided example arguments.

   // in another terminal (i.e. not in eth client or server terminals)
   truffle exec server/calls.js

Remote

Trusource currently supports the Ropsten test network (see list of supported networks here).

To deploy to a live network (e.g. Ropsten):

1. Uncomment line 4 to 12 in truffle-config.js.

2. Set the SEED_PHRASE (mnemonic) and ETHEREUM_RPC_URL environment variables in .env.

3. Migrate the contracts.

   truffle migrate --network ropsten

4. Whitelist the contract that will call the LiveScore API at Trusource.io.

Folder structure

The structure is similar to a standard Truffle project. The difference is the additional server directory.

├── build                   # Compiled files
├── contracts               # Solidity contracts
├── migrations              # Deployment files
├── server                  # Local server test script
├── test                    # Test files for testing contracts
├── .env.template
├── .solhint.json
├── package.json
├── LICENSE
├── README.md
├── .truffle-box.json
└── truffle.config.js       # Truffle configuration file

contracts

Example.sol inherits the LiveScore OracleAPI and demonstrates usage of its operations. OracleAPI.sol, Oracle.sol, and Resolver.sol make up the oracle architecture and must be unchanged.

See here for more details.

server

calls.js runs a set of example calls on Example.sol, see Local Development for instructions. oas.json is the OpenAPI specification of the LiveScore API used by the local server, it must remain unchanged. If it is lost or changed, it can be found here.

See here for more details.

test

Tests are written in JavaScript and ensure contract calls execute without failure, events are correctly emitted and the callback is implemented.

.env.template

cp .env.template .env

The LiveScore API requires authentication, please sign up for the free tier and obtain credentials. Provide these credentials in and rename the file to .env. These credentials with be used for authentication when running the local development tests.

Testing

Truffle can run tests written in Solidity or JavaScript against your smart contracts. Note that an Ethereum client must be running.

truffle test

Linting

We use Solhint to lint the code - you can run it using npm run lint.

FAQ

• What is a blockchain oracle?

  Blockchain oracles are third-party services that provide smart contracts with external information. They serve as bridges between blockchains and the outside world. -- Binance

• What about truffle develop?

  We do not recommend using truffle develop because the command spawns a development blockchain that lacks WebSockets support. You will be able to compile and migrate contracts just fine.

  Error: The current provider doesn't support subscriptions: HttpProvider will appear when running npm run calls or npm test. We subscribe to LogResult events in the server/calls.js Truffle script.

  More details about the differences between truffle console and truffle develop on Truffle's website.

• Changing ports

  ganache-cli and @trusource/server both defaults to port 8545. Both can be changed by running with -p option. You will then need to update the port value in the development object in networks in truffle-config.json.

License

MIT