From f3256f58130784860f89ba82609b328e7e30f419 Mon Sep 17 00:00:00 2001 From: n0izn0iz Date: Mon, 25 Mar 2024 14:57:59 +0100 Subject: [PATCH] chore: add more technology definitions to CONTRIBUTING.md (#1138) * chore: add more technology definitions to CONTRIBUTING.md * Update CONTRIBUTING.md --- CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c932aeed0e..27be3869c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,11 +58,67 @@ You can deny the review if the PR does not pass CI ### Frontend -TODO +#### Language: Typescript + +We use a strict [Typescript](https://www.typescriptlang.org/docs/handbook/intro.html) configuration and try to enforce type-safety. Typescript very easily allows to bypass it's type-safety mechanism so it requires some discipline from the developer. + +#### Framework: Expo + +We use [the Expo framework](https://docs.expo.dev/) to support Web, Android, iOS, Windows, Macos and Linux with the same codebase. +This uses [react-native](https://reactnative.dev/docs/getting-started) to support mobile and [react-native-web](https://necolas.github.io/react-native-web/docs/) for web. The desktop build uses electron and react-native-web. + +If you are coming from React and you work with the web dev server, it's important to understand that using html components (eg `
`) and styles will work because the react-native-web renderer allows it but it won't work with native renderers (iOS, Android and native desktop). So please check the expo api reference to make sure you are using things that are truly cross-platform. + +#### Data fetching: react-query + +We use [react-query](https://tanstack.com/query/v4/docs/framework/react/overview) to fetch data. It provides call-deduplication and configurable caching. +You can use it for optimistic mutations too but in most mutations case an async callback is enough. + +#### App state: redux + +We use [redux](https://redux-toolkit.js.org/) for global app state, it supports persistence. We're considering switching to [zustand](https://github.com/pmndrs/zustand). ### Backend -TODO +#### Decentralized services: Cosmos SDK + +The main service for the Teritori chain is the Teritori blockchain daemon, [teritorid](https://github.com/TERITORI/teritori-chain). +But a lot of features we're developing are cross-chain compatible and use common [Cosmos SDK](https://docs.cosmos.network/) APIs. +Cosmos blockchain are configurable and you can see the list of modules for the Teritori chain [here](https://github.com/TERITORI/teritori-chain/blob/v2.0.6/app/app.go#L210-L238) for example. + +You can find the main Cosmos API documentation [here](https://docs.cosmos.network/api). + +Cosmos provides a native way for inter-blockchain communication called [IBC](https://cosmos.network/ibc/). It allows to transfer currencies between chains and more complex cross-chain behavior, for example swapping funds on Osmosis from a DAO on Teritori while keeping funds sovereignty by the DAO. + +#### Smart contracts: CosmWASM + +Smart-contracts are programs that run on blockchains. + +The smart-contracts on teritori chain and most cosmos chains are using [cosmwasm](https://book.cosmwasm.com/) and thus [rust](https://www.rust-lang.org/) as programing language. + +We recommend to use the [sylvia framework](https://cosmwasm.github.io/sylvia-book/index.html) to write your cosmwasm contracts as it heavily reduces boilerplate, making the code easier to maintain and read. It also provides better testing utilities. + +#### Indexer: golang + postgres + substreams + +Some chain data need to be aggregated and indexed to allow for performant queries. For example the marketplace stats that is aggregating the trade amounts for a month or indexing all nfts for an user so we can efficiently show the owned nfts of an user. +The cosmos-targeted indexer uses a custom golang daemon and the native cosmos apis to query for transactions in order and index them. +The evm-targeted indexer (supporting ethereum and polygon for now) uses the [substreams](https://substreams.streamingfast.io/) firehose api and we intend to use substream for cosmos too. + +#### Extra services: golang + +We have additional services to serve custom aggregates that are not provided by the chain and some off-chain features (eg private user data). +We recommend [golang](https://go.dev/doc/) to write additional services, it's not a strict rule but golang is a good middle ground between performance and ease-of-use with a strong focus on maintainability. +The Cosmos SDK itself is written in golang. + +#### Protocol for extra services: GRPC + +We use [GRPC](https://grpc.io/) as communication protocol for the centralized APIs. The models and endpoints definition are written in [protobuf](https://protobuf.dev/), this allows to generate types, servers and clients in any language. The definition are in the [api folder](api). The backend servers in the [go/pkg folder](go/pkg). The clients in the [js/packages/api folder](js/packages/api). + +The Cosmos SDK is also using protobuf for it's endpoints definition but with custom encodings and extra layers on top of it. + +#### Future: Gno + +We plan to transition from Cosmos SDK to [Gno](https://docs.gno.land/) for the blockchain nodes and smart-contracts framework ## Patterns