README ¶
stonechat
Chainlink External Adapter for Google Sheets
Introduction
Google Sheets is more than just a simple spreadsheet. Its a proving ground for new business ideas, tokenomics, ideation and prototyping. Stonechat is a Chainlink Adapter that helps node operators build a bridge to Google Sheets, so that web3 development teams can integrate data held in Google Sheets into their smart contracts.
Web3 teams can combine Chainlink Oracles and Google Sheets together to rapidly prototype new solutions by generating the right data in Google Sheets and using the adapter to bring the data on-chain.
The adapter supports the fetching of individual cells, rows, columns, and ranges. The adapter also performs type conversions to convert data into more compatible formats, such as from dates to EVM timestamps.
Ingredients you will need
You will need the following to get up and running with Stonechat
- Google Sheet with some meaningfull data on it.
- Google Sheets API key to programmatically allow access to the Google Sheet
- A hosted instance of Stonechat.
Hosting Stonechat
You have three options to host and run Stonechat
- Build it from scratch, including your own Docker container image, and run it in the cloud on AWS, Heroku, Fly.io (recommended)
- Use our latest Docker container image from Docker Hub and run it in the cloud.
- Get us to to host the external adapter for you. Come find us in the Translucent Discord.
Using the Stonechat
Lets use the following spreadsheet as an example:
Cells
By calling the external adapter with the following path query
/cell/:column/:row/:returnType
/cell/c/2/b
Stonechat will return
{
"data": {
"value": true
}
}
By calling the external adapter with the following path query
/cell/b/2/n
Stonechat will return
{
"data": {
"value": 27
}
}
Columns
By calling the external adapter with the following path query
/column/:column/:startRow/:endRow/:returnType
/column/d/2/4/t
Stonechat will return
{
"data": {
"value": [
1617231600,
1623625200,
0
]
}
}
Rows
By calling the external adapter with the following path query
/row/:startColumn/:endColumn/:row/:returnType
/row/e/g/1/s
Stonechat will return
{
"data": {
"value": [
"Choice 1",
"Choice 2",
"Choice 3"
]
}
}
Ranges
By calling the external adapter with the following path query
/range/:startColumn/:startRow/:endColumn/:endRow/:returnType
/range/e/2/g/4/n
Stonechat will return
{
"data": {
"value": [
[
1,
2,
3
],
[
4,
5,
6
],
[
7,
8
]
]
}
}
Return Types
Stonechat has the ability to convert (best effort) any data it retrieves into a native JSON-type. The last parameter on the path definitions shown above is the :returnType
. The following return types are currently supported.
s
- returns a string by converting source data to string.b
- return a booltrue
if the source data is some form of case-insensitive "TRUE", otherwisefalse
.n
- returns a number converting source data to afloat64
.t
- converts a date-value to the number of seconds since the epoch, making it compatible withblock.timestamp
Note: date-parsing is highly dependent on date formats. See the environment section below to configure date formats.
POST instead of GET
The adapter supports using POST as the HTTP method, instead of GET:
POST /cell
POST /column
POST /row
POST /range
In each of POST /uri
cases above the expected payload is a JSON payload with the values that are normally passed in on the path of a GET /uri
request, e.g. :returnType.
POST /range
{
"startColumn": "b",
"endColumn": "d",
"startRow": 2,
"endRow": 4,
"returnType": "n"
}
Chainlink Jobs
The return values and types are intended to be compatible with the basic jobs that most node operators offer to the market, such as
- Get > Uint256
- Get > Uint256[]
- Get > Bool
- Get > Bytes
- Post > Uint256
- Post > Uint256[]
- Post > Bool
- Post > Bytes
- etc.
Building Stonechat
Getting started
-
Clone the Stonechat repo and download the repo.
-
Install the go-dependencies
go mod tidy
-
Run the server locally
go run *.go
You should be able to access the following URLs:
- http://localhost:8080/cell - Main endpoint
- http://localhost:8080/health - Simple health=OK endpoint
- http://localhost:8080/metrics - Prometheus-based metrics endpoint
Building & Shipping
To dockerize and upload the Docker container image run the build script:
bin/build.sh 0.0.1
The above command will generate a Linux/AMD64-compatible Docker container image and upload it to Docker.io's Hub (it assumes you're logged in with docker login
). The 0.0.1
parameter above is used to tag the container image.
NOTE: You should customise the translucentlink/stonechat
references in the build.sh
to make them work with your Docker credentials, e.g. replace them with my-acme-corp/price-feed
.
Deployment
How you deploy the container is up to you (Docker, AWS, Kubernetes, etc.) but nothing is quite as fast & convenient as using Fly.io
flyctl launch --image=translucentlink/stonechat:0.0.1
If you haven't got the flyctl
command installed, check out their 2-minute intro on installing and logging in.
To access your deployed external adapter
flyctl open
To deploy an update to your external adapter
bin/build.sh 0.0.2
flyctl deploy --image=translucentlink/stonechat:0.0.2
The example container is deployed at https://ethusd-example.fly.dev/.
Environment
The application uses a couple of environment variables to configure its behaviour
SHEETS_ID=12rb-uVQsjMWk1GLv6MWXoHHPTY-erUaKVxY4JrdFdHK
SHEETS_API_KEY=AB................................e0
SHEETS_TAB_NAME=Sheet1
SHEETS_DATE_FORMAT=DD/MM/YYYY
SHEETS_ID
refers to the id (found in the URL) of the Google Sheet you're trying to accessSHEETS_API_KEY
refers to the API key used to programmatically gain access to the Google SheetSHEETS_TAB_NAME
refers to the name of the Google Sheet tab you're trying to access, e.g Sheet1SHEETS_DATE_FORMAT
used by the timestamp return type to parse and convert a date into a timestamp object.
Support & Help
Feel free to open a Github Issue or come find us in the Translucent Discord.
Documentation ¶
There is no documentation for this package.