Skip to content

Latest commit

 

History

History
157 lines (97 loc) · 6.14 KB

README.md

File metadata and controls

157 lines (97 loc) · 6.14 KB
Raw

Governance SDK

The Governance SDK is a portable protocol agnostic governance interoperability framework built for NodeJS and the browser. It makes it easier for developers to query and interact with protocol governance in a normalized way by leveraging community-authored protocol integrations.

Our goal is to ensure adding protocol integrations is as streamlined as possible and flexible enough to capture the functionalities of differing governance frameworks. To do this, we will focus on enabling the most common and frequently-used governance interactions in order to prioritize a horizontal-first approach to integrations.

For usage and guides on actually using the SDK, see the GitBook documentation:

The in-repo documentation will primarily focus on architecture and implementation details.

Repo Structure

The project is structured as a monorepo managed by lerna.

Package Topology

Screen Shot 2021-09-21 at 2 52 34 PM

  • gov-lib - Core interopability models, adapter interfaces, and utility code. No protocol- or framework-specific code.
  • gov-adapters - Adapter implementations for various frameworks (such as SnapshotAdapter, CoinGeckoAdapter)
  • gov-protocols - Uses adapter implementations from gov-adapters to "wire up" protocol integrations
  • gov-sdk - Combines all of the above with a simple GovernanceSDK facade. The main package SDK consumers will install.

Scripts

  • Packages should implement any cleanup of build artifacts, caches, etc in an optional clean npm script.

IDE Integration

To help onboard contribution, portable IDE configuration should be checked into the repo.

Architecture

Screen Shot 2021-09-22 at 8 47 54 AM

The Client (SDK consumer) must instantiate the GovernanceSDK from the gov-sdk package, optionally providing a subset of various transports that interact with external data sources.

The SDK manages the collection of protocol integrations, which are defined by imperative protocol registration functions in gov-protocols. These functions register information about a protocol and instantiate adapter instances that that implement the adapter interfaces defined by the core gov-lib package.

Common adapter implementations are shipped in the gov-adapters package for governance frameworks.

Design Rationale

  • The injected pattern with transports is to ensure that the SDK consumer can provide their own implementation for talking to external data sources. This allows all SDK code to depend on simple transport interfaces fullfilled by client- and environment-specific implementations. This also provides a good path for unit testing via mocked transports.
  • The seperation of adpater interfaces (in gov-lib) and their implementation (in gov-adapters) is intentional. Adapter interfaces ideally can be fullfilled by several different implementations, as we want to abstract downstream differences behind our interopability model.
  • Protocol registration functions are imperative to allow for more sophisticated or complex approaches to protocol integrations. This allows a single function to register several protocols at once (DAOHaus), or enable environment-specific logic (conditionally registering test protocols), or use registion abstractions/utilities in the future.
  • Protocols are composed-of adapter instances. This ensures that as we expand our interop model to accomodate more types of data and interaction, we have the design space to add more functionality without having to break backwards compatability. The library of adapter interfaces will continue to grow, while SDK client code can rely on old adapters working as they do today.

Development

Requirements:

  • NodeJS v14 (nvm recommended)

Install all dependencies in all packages and bootstrap the monorepo:

$ npm i

Lint and validate all TypeScript:

$ npm run lint

Run all TypeScript unit tests:

$ npm test

Build all packages (not required for normal local dev / testing):

$ npm run build

To assert no regressions in package exports:

$ npm run test:package-snapshots

Remove all build artifacts:

$ npm run clean

Remove all build artifacts and dependencies in all packages:

$ npm run nuke

Publishing

Several packages from this monorepo are published to npm as transient dependencies of the main @boardroom/gov-sdk package.

To publish, make sure you have built all package artifacts:

$ npm run build

Then bump the packaged based on conventional commits (detects major vs minor vs patch). This will push the tags and commit to the remote as well

$ npm run version:bump

Finally, publish to npm:

$ npm run publish

If you are using VS Code, there is "🚀 Rebuild, tag, and publish a new version" task that executes all of the above.

Additional Scripts

Run the reference client in debug mode (reloads on changes):

$ npm run client:dev

To compile the reference client (not using the build command because we don't need to the client to build alongside the actual library packages, this is mostly to assert client-side compilation works with the SDK):

$ npm run client:compile

Re-build the package outputs and re-run any snapshot tests:

$ npm run snapshots:update

Check the parity with the protocol-Info repo (ensure latest package version in ./packages/script-parity-check/package.json):

$ npm run parity:check

Additional Automation

  • .github/workflows for GitHub action automation. This can be setup to gate PRs with certain build/test conditions or eventually automatically publish to NPM if desired
  • .vscode/tasks.json for VS Code specific tasks. Because not everyone will use VS Code, this should strictly be convenient shortcuts for other scripts
  • package.json for all npm scripts

License

MIT