@owlprotocol/contracts-api

Contracts API

Our API for the contracts, with TRPC support.

Development

Generate routes

pnpm run codegen

• Note: this is also run when calling the build script

Express server

pnpm run build && pnpm run express

Expose local server online

pnpm run express
# In a separate terminal
pnpm run ngrok

• Note: requires ngrok installed
• Useful to test webhook with ReadMe

Build Docker image

From the workspace root:

docker build . -f Dockerfile -t vulcanlink/contracts-api:${VERSION:-test} --target contracts-api

Management Consoles

Relevant management consoles for tech stack:

• Firebase: https://console.firebase.google.com/u/0/project/owl-protocol/overview
• Readme.io: https://dash.readme.com/project/owlprotocol/v0.0/overview
• DFNS: https://app.dfns.ninja/
• NGrok: https://dashboard.ngrok.com/

Local Gnosis

Clone the safe-contracts repo on your computer.

git clone [e-mail]:safe-global/safe-contracts.git && cd safe-contracts

Set the .env file.

MNEMONIC="test test test test test test test test test test test junk"
NODE_URL="http://localhost:8545"

Compile and deploy locally.

yarn build && yarn deploy-all custom

Testing with Firebase Emulator

https://firebase.google.com/docs/emulator-suite

Install Firebase CLI & Run Emulator

curl -sL https://firebase.tools | bash
# Either works
firebase emulators:start
pnpm run firebase-emulator

Go to http://127.0.0.1:4000/firestore/data to view data.

Run tests

# Either works
npm run test
pnpm exec vitest src/path_to_file.ts #install vitest globally, broken when run directly

Testing Local Server w/Anvil + Firestore Emulator

# Start Firebase Emulator
pnpm run firebase-emulator
# Start Anvil Node
pnpm run anvil
# Run Dev Server Setup (Upload Firebase Data, Deploy Contracts) & Start Express Server
# Note: Error logs are to be expected for invalid abis
pnpm run express:dev
# Run the indexer (from packages/contracts-indexer folder)
cd ../contracts-indexer && pnpm run start

Testing Local Server w/Readme.io

While you can test the endpoints locally via Swaggerhub, certain features such as the Readme webhook & Readme recipes can only be tested via the readme.io UI. To test these features without having to re-deploy the API, we can create a local proxy using ngrok.

Build, Run, Expose

Install and configure ngrok using at dashboard.ngrok.com/get-started/setup We first run build & run the server, and then expose it publicly using ngrok.

npm run build & npm run express # Run localhost server
ngrok http 3000                   # Expose localhost server

Copy the "Forwarding" endpoint.

Readme.io OpenAPI config

Now we configure a new OAS spec. This will enable us to define new routes we've developed and set the url endpoint to be our ngrok endpoint.

• Generate OpenAPI spec with patched server endpoint
• Upload new OpenAPI spec using rdme CLI

Generate a new OpenAPI spec but patch it with the ngrok endpoint. We have a script for this that saves the new spec under readme/v0.0/openapi.json

node lib/esm/openapiSave.js v0.0 <ngrokUrl>

Install the CLI if not present already. Login with your readme.io login info.

pnpm install -g rdme
rdme login --email <email> --password <password>

Sync openapi spec by fetching the spec from localhost. We set version as v0.0 as the private version we use for testing (this is ignored but useful to keep in mind for other operations). We use the hardcoded 64cfafdc8cc6da00656ad092 spec to just update it.

rdme openapi readme/v0.0/openapi.json --version v0.0 --id "64cfafdc8cc6da00656ad092" --update

Generate a user & api key

We create a user and have it associated with one of our generated api keys.

• Go to (owlprotocol/v0.0/metrics/setup-api-keys)[https://dash.readme.com/project/owlprotocol/v0.0/metrics/setup-api-keys]
• Click "Edit Configuration"
• Add the https://XXXX-XXX-XXX-XX-XXX.ngrok-free.app/api/webhooks/readme and an email
• Click "Try it", this should return an api key and user info. (Note: This sometimes fails but simply retry)

This should kick start the signup process:

• Generate user with api key on Firebase
• Issue DFNS wallet creation request
• Deploy Gnosis Smart Wallet for user and save tx hash

Updating Readme.io Guides

Readme metadata is stored under ./readme indexed by version. We store 3 core types of data:

• openapi.json: The generated OpenAPI spec. Pushed to readme.io using CLI.
• recipes: Recipes. Stored here but edited manually at docs-api.owlprotocol.xyz/recipes
• guides: Guides. Edited here and pushed to readme.io using CLI.

Open API

See above section "Readme.io OpenAPI config".

• Run the server npm run build & npm run express
• Run openapi script node lib/esm/openapiSave.js <version> <url> (this updates local json)
• Push to readme.io rdme openapi readme/<version>/openapi.json --version <version> --update

Recipes

• First edit local markdown & code examples
• Replicate these edits on docs-api.owlprotocol.xyz/recipes

Guides

• Edit local markdown files
• Push to readme rdme docs readme/<version>/guides --version=<version> --dryRun

Webhooks

• readme: $HOST/api/webhooks/readme/auth
• clerk: $HOST/api/webhooks/clerk
• shopify: TODO

Routes

Overview of general API routes.

# Webhook
/webhooks/readme                                                            # Readme.io webhook for signups
# OpenAPI Swagger UI
/                                                                           # OpenAPI UI
# OpenAPI Spec
/api/openapi.json                                                           # OpenAPI Spec

# TRPC
/api/trpc                                                                   # TRPC endpoint

# TRPC w/OpenAPI
## Webhooks
/api/webhooks/readme                                                        # Readme webhook

## User routes
/api/user/me                                                                # Get current user info
/api/user/me/contracts                                                      # Get current user contracts
/api/user/<userId>                                                          # Get by id user info (Disabled: Requires proper permissions)
/api/user/<userId>/contracts                                                # Get by id contracts (Disabled: Requires proper permissions)
/api/user/requestTemplates                                                  # Get user request templates

## Eth routes
/api/<networkId>/broadcastTx                                                # Broadcast transaction
/api/<networkId>/signTx                                                     # Sign transaction
/api/<networkId>/rpc                                                        # RPC Proxy
/api/<networkId>/ws                                                         # Websocket Proxy

## Contract routes
/api/<networkId>/interfaces/<contract>/read/<address>/<function>            # Read data
/api/<networkId>/interfaces/<contract>/write/<address>/<function>           # Write data, sending transaction
/api/<networkId>/interfaces/<contract>/writeUnsigned/<address>/<function>   # Write data, get unsigned payload
/api/<networkId>/deploy/<contract>                                          # Deploy smart contract

## Business Abstraction routes
/api/<networkId>/collection                                                 # Deploy NFT collection

## Topup Routes (abstraction for credits)
/api/<networkId>/topup/erc20/<address>                                      # Topup ERC20 (eg. LINK)
/api/<networkId>/topup/native                                               # Topup native tokens (eg. Eth)
/api/<networkId>/

## Gnosis Safe Routes (abstraction over smart wallet)
/api/<networkId>/safe/<address>                                             # Gnosis Safe info