Licensed to the Apache Software Foundation (ASF) under one

or more contributor license agreements. See the NOTICE file

distributed with this work for additional information

regarding copyright ownership. The ASF licenses this file

to you under the Apache License, Version 2.0 (the

"License"); you may not use this file except in compliance

with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,

software distributed under the License is distributed on an

"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

KIND, either express or implied. See the License for the

specific language governing permissions and limitations

under the License.

Smart Contracts GraphQL API

This repository provides a GraphQL API that allows users to interact with smart contracts in the ResilientDB ecosystem through a set of GraphQL queries and mutations. The API leverages the rescontract-cli tool to perform various functions, including creating accounts, compiling contracts, deploying contracts, and executing contract functions.

Table of Contents

• Prerequisites
• Installation
• Configuration
• Running the Server
• GraphQL API
• Mutations
• Sample Mutations
  • Using Type “path”
  • Using Type “data”
• Contributing
• License

Prerequisites

Before you begin, ensure you have the following prerequisites:

1. ResilientDB: A running instance of ResilientDB with the smart contracts service running. More information and setup instructions can be found here: ResilientDB

2. ResContract CLI: Install the rescontract-cli tool globally. Follow the instructions in the ResContract CLI Repository to install and configure it.

npm install -g rescontract-cli

1. Node.js (version >= 15.6.0): Download and install Node.js version 15.6.0 or higher, as the application uses crypto.randomUUID() which was introduced in Node.js v15.6.0.

   # You can check your Node.js version with:
   node -v
   

The prerequisites listed above can be installed using the INSTALL.sh script:

chmod +x INSTALL.sh
./INSTALL.sh

Installation

To set up the project, follow these steps:

1. Clone the repository:

   git clone https://github.com/ResilientEcosystem/smart-contracts-graphql.git
   cd smart-contracts-graphql
   

2. Install dependencies:

    npm install
   

Configuration

Ensure that the ResContract CLI is properly configured. You need to set the ResDB_Home environment variable or provide a config.yaml file as required by the CLI.

Refer to the ResContract CLI README for detailed instructions.

Running the Server

Start the server using the following command:

npm start

The server will start running on port 8400. You can access the GraphQL API at http://localhost:8400/graphql.

GraphQL API

The GraphQL API supports the following mutations to interact with smart contracts.

Mutations

createAccount

Creates a new account using the specified configuration file.

Type: Mutation

Arguments:

• config (String!): Configuration data or path to the configuration file.
• type (String): Optional. Specifies whether config is data or a file path. Accepts "data" or "path". Defaults to "path".

Returns: String - Address of the newly created account or an error message.

compileContract

Compiles a smart contract from the specified source.

Type: Mutation

Arguments:

• source (String!): Solidity code or path to the source file of the smart contract.
• type (String): Optional. Specifies whether config is data or a file path. Accepts "data" or "path". Defaults to "path".

Returns: String - Name of the compiled contract JSON file or an error message.

deployContract

Deploys a smart contract using the specified configuration, contract file, contract name, arguments, and owner address.

Type: Mutation

Arguments:

• config (String!): Configuration data or path to the configuration file.
• contract (String!): Path to the contract JSON file.
• name (String!): Name of the contract (include the full path and contract name).
• arguments (String!): Constructor arguments for the contract (comma-separated).
• owner (String!): Owner address.
• type (String): Optional. Specifies whether config is data or a file path. Accepts "data" or "path". Defaults to "path".

Returns: String - Details of the deployed contract or an error message.

executeContract

Executes a function of a deployed smart contract.

Type: Mutation

Arguments:

• config (String!): Configuration data or path to the configuration file.
• sender (String!): Address of the sender.
• contract (String!): Address of the deployed contract.
• functionName (String!): Name of the function to execute (include parameter types).
• arguments (String!): Arguments for the function (comma-separated).
• type (String): Optional. Specifies whether config is data or a file path. Accepts "data" or "path". Defaults to "path".

Returns: String - Result of the function execution or an error message.

Sample Mutations

Below are sample mutations demonstrating how to use the API with both "path" and "data" types.

Using type path

The type option defaults to "path" and doesn't have to be explicitly set.

1. Create Account

mutation {
  createAccount(config: "../incubator-resilientdb/service/tools/config/interface/service.config")
}

Sample Response:

{
  "data": {
    "createAccount": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
  }
}

Explanation: Creates a new account using the configuration file located at the specified path.

1. Compile Contract

   mutation {
     compileContract(
       source: "token.sol"
     )
   }
   

Sample Response:

{
  "data": {
    "compileContract": "Compiled successfully to /users/yourusername/smart-contracts-graphql/compiled_contracts/MyContract.json"
  }
}

Explanation: Compiles the smart contract located at token.sol and saves the compiled JSON to the compiled_contracts directory.

1. Deploy Contract

   mutation {
     deployContract(
       config: "../incubator-resilientdb/service/tools/config/interface/service.config",
       contract: "compiled_contracts/MyContract.json",
       name: "token.sol:Token",
       arguments: "1000",
       owner: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8"
     )
     {
       ownerAddress
       contractAddress
       contractName
     }
   }
   

Sample Response:

{
  "data": {
    "deployContract": {
      "ownerAddress": "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8",
      "contractAddress": "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1",
      "contractName": "token.sol:Token"
    }
  }
}

Explanation: Deploys the compiled contract using the specified parameters.

1. Execute Contract

   mutation {
     executeContract(
       config: "../incubator-resilientdb/service/tools/config/interface/service.config",
       sender: "0x67c6697351ff4aec29cdbaabf2fbe3467cc254f8",
       contract: "0xfc08e5bfebdcf7bb4cf5aafc29be03c1d53898f1",
       functionName: "transfer(address,uint256)",
       arguments: "0x1be8e78d765a2e63339fc99a66320db73158a35a,100"
     )
   }
   

Sample Response:

{
  "data": {
    "executeContract": "Execution successful"
  }
}

Explanation: Executes the transfer function of the deployed contract, transferring 100 tokens to the specified address.

Using type data

In this mode, the API accepts configuration data and Solidity code directly, without needing file paths.

1. Create Account

mutation {
  createAccount(
    config: "5 127.0.0.1 10005",
    type: "data"
  )
}

Sample Response:

{
  "data": {
    "createAccount": "0x255d051758e95ed4abb2cdc69bb454110e827441"
  }
}

Explanation: Creates a new account using the provided configuration data.

1. Compile Contract

   mutation {
     compileContract(
       source: """
       pragma solidity ^0.8.0;
           ...
           ...
       }
       """,
       type: "data"
     )
   }
   

Sample Response:

{
  "data": {
    "compileContract": "contract-20f42b42-f56f-45e8-8264-33cf8d93f8be.json"
  }
}

Explanation: Compiles the provided Solidity code and returns the name of the compiled contract JSON file stored in the compiled_contracts directory.

1. Deploy Contract

   mutation {
     deployContract(
       config: "5 127.0.0.1 10005",
       contract: "contract-20f42b42-f56f-45e8-8264-33cf8d93f8be.json",
       name: "/path/to/.json/file:Token",
       arguments: "1000",
       owner: "0x255d051758e95ed4abb2cdc69bb454110e827441",
       type: "data"
     )
   }
   

Sample Response:

{
  "data": {
    "deployContract": "owner_address: 0x255d051758e95ed4abb2cdc69bb454110e827441\ncontract_address: 0xb616e4c564b03fe336333758739a7d7ee0227d5d\ncontract_name: Token"
  }
}

Explanation: Deploys the compiled contract using the configuration data and the compiled contract JSON file name returned from the compileContract mutation.

1. Execute Contract

   mutation {
     executeContract(
       config: "5 127.0.0.1 10005",
       sender: "0x255d051758e95ed4abb2cdc69bb454110e827441",
       contract: "0xb616e4c564b03fe336333758739a7d7ee0227d5d",
       functionName: "transfer(address,uint256)",
       arguments: "0x213ddc8770e93ea141e1fc673e017e97eadc6b96,100",
       type: "data"
     )
   }
   

Sample Response:

{
  "data": {
    "executeContract": "result: 0x0000000000000000000000000000000000000000000000000000000000000001"
  }
}

Explanation: Executes the transfer function of the deployed contract, transferring 100 tokens to the specified address, using configuration data.

License

This project is licensed under the Apache License - see the LICENSE file for details.