¶
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
- Contributing
- License
Prerequisites¶
Before you begin, ensure you have the following prerequisites:
-
ResilientDB: A running instance of ResilientDB with the smart contracts service running. More information and setup instructions can be found here: ResilientDB
-
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
-
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:
-
Clone the repository:
git clone https://github.com/ResilientEcosystem/smart-contracts-graphql.git cd smart-contracts-graphql
-
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.
- 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.
- Compile Contract
mutation { compileContract( source: "token.sol" ) }
Sample Response:
{
"data": {
"compileContract": "Compiled successfully to /users/yourusername/smart-contracts-graphql/compiled_contracts/MyContract.json"
}
}
- 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"
}
}
}
- 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"
}
}
Using type data
¶
In this mode, the API accepts configuration data and Solidity code directly, without needing file paths.
- 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.
- Compile Contract
mutation { compileContract( source: """ pragma solidity ^0.8.0; ... ... } """, type: "data" ) }
Sample Response:
{
"data": {
"compileContract": "contract-20f42b42-f56f-45e8-8264-33cf8d93f8be.json"
}
}
- 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"
}
}
- 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"
}
}
License¶
This project is licensed under the Apache License - see the LICENSE file for details.