|
| 1 | +# Maintainer Guide |
| 2 | + |
| 3 | +This document is intended for **SDK maintainers** who need to update the proto definitions, chain types, or generated data files when a new `injective-core` or `injective-indexer` release is published. SDK users only need [README.md](README.md). |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 1. Configuring the upstream versions (do this first) |
| 8 | + |
| 9 | +Before running any update command, set the upstream version tags in [Makefile](Makefile). The two targets that clone the upstream repositories each carry a `-b <tag>` flag that determines which version all downstream steps will draw from: |
| 10 | + |
| 11 | +```makefile |
| 12 | +clone-injective-indexer: |
| 13 | + git clone https://github.com/InjectiveLabs/injective-indexer.git -b v1.19.0 --depth 1 --single-branch |
| 14 | + |
| 15 | +clone-injective-core: |
| 16 | + git clone https://github.com/InjectiveLabs/injective-core.git -b v1.19.0 --depth 1 --single-branch |
| 17 | +``` |
| 18 | + |
| 19 | +To update to a new release (e.g. `v1.20.0`), change both tags: |
| 20 | + |
| 21 | +```makefile |
| 22 | +clone-injective-indexer: |
| 23 | + git clone https://github.com/InjectiveLabs/injective-indexer.git -b v1.20.0 --depth 1 --single-branch |
| 24 | + |
| 25 | +clone-injective-core: |
| 26 | + git clone https://github.com/InjectiveLabs/injective-core.git -b v1.20.0 --depth 1 --single-branch |
| 27 | +``` |
| 28 | + |
| 29 | +Both versions should be kept in sync with the same chain release tag. These two lines are the single source of truth that drives every downstream step: exchange API bindings, chain module types, the `proto/` tree, and the auto-generated `injective_data/chain_messages_list.json`. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## 2. Updating Exchange API bindings |
| 34 | + |
| 35 | +```bash |
| 36 | +make copy-exchange-client |
| 37 | +``` |
| 38 | + |
| 39 | +This target (which internally calls `clone-injective-indexer`): |
| 40 | + |
| 41 | +1. Removes the entire `exchange/` directory. |
| 42 | +2. Recreates per-service `pb/` subdirectories under `exchange/`. |
| 43 | +3. Copies the already-generated `*.pb.go` files from `injective-indexer/api/gen/grpc/.../pb/` into the corresponding `exchange/...` paths. |
| 44 | +4. Removes the cloned `injective-indexer` directory. |
| 45 | + |
| 46 | +No local proto generation runs — the SDK consumes the indexer's pre-generated Go bindings directly. |
| 47 | + |
| 48 | +The version cloned is determined by the `-b <tag>` flag in the `clone-injective-indexer` target (see [section 1](#1-configuring-the-upstream-versions-do-this-first)). |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## 3. Updating chain types and proto |
| 53 | + |
| 54 | +```bash |
| 55 | +make copy-chain-types |
| 56 | +``` |
| 57 | + |
| 58 | +This target (which internally calls `clone-injective-core`) performs the following steps: |
| 59 | + |
| 60 | +1. Copies `codec`, `crypto/*`, and per-module `types/` directories from `injective-core/injective-chain/...` into the corresponding `chain/...` paths. For most modules only `*.pb.go` and `codec.go` are copied; for `exchange`, `evm`, `oracle`, `peggy`, and `wasmx`, additional hand-written `.go` source files are also included. Files matching `*test.go` and `*gw.go` are stripped. |
| 61 | +2. Copies the `proto/` tree from `injective-core/proto` into `proto/`, replacing the previous contents entirely. |
| 62 | +3. Rewrites all import paths in-place across every copied `.go` file so that `github.com/InjectiveLabs/injective-core/injective-chain[/modules]` becomes `github.com/InjectiveLabs/sdk-go/chain`. This rewrite uses BSD `sed -i ""` syntax, which works on macOS. **Linux maintainers must use GNU `sed -i` instead** — either edit the Makefile temporarily or run the step on macOS. |
| 63 | +4. Removes the cloned `injective-core` directory. |
| 64 | +5. Automatically invokes `make extract-message-names` to regenerate `injective_data/chain_messages_list.json` from the freshly copied types. |
| 65 | + |
| 66 | +The version cloned is determined by the `-b <tag>` flag in the `clone-injective-core` target (see [section 1](#1-configuring-the-upstream-versions-do-this-first)). |
| 67 | + |
| 68 | +### Syncing `go.mod` |
| 69 | + |
| 70 | +`make copy-chain-types` does **not** update [go.mod](go.mod) automatically. After running it, manually align the SDK's `go.mod` dependencies with those declared in `injective-core`'s `go.mod` for the target tag. The reference file is available directly on GitHub: |
| 71 | + |
| 72 | +``` |
| 73 | +https://github.com/InjectiveLabs/injective-core/blob/<tag>/go.mod |
| 74 | +``` |
| 75 | + |
| 76 | +After applying the changes, run: |
| 77 | + |
| 78 | +```bash |
| 79 | +go mod tidy |
| 80 | +``` |
| 81 | + |
| 82 | +Failing to do this after a version bump will typically produce compile errors or mismatched dependency versions. |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +## 4. Generated data files |
| 87 | + |
| 88 | +### `injective_data/chain_messages_list.json` |
| 89 | + |
| 90 | +This file is regenerated automatically at the end of `make copy-chain-types` via the `extract-message-names` target. It can also be regenerated independently: |
| 91 | + |
| 92 | +```bash |
| 93 | +make extract-message-names |
| 94 | +``` |
| 95 | + |
| 96 | +The pipeline: |
| 97 | +1. Searches every `tx.pb.go` and `msgs.pb.go` file under `chain/` for `proto.RegisterType(...)` calls. |
| 98 | +2. Extracts the fully-qualified proto type name from each call (e.g. `injective.exchange.v1beta1.MsgCreateSpotMarketOrder`). |
| 99 | +3. Drops any name ending in `Response`. |
| 100 | +4. Deduplicates and sorts the result. |
| 101 | +5. Writes the final JSON array to `injective_data/chain_messages_list.json` using `jq`. |
| 102 | + |
| 103 | +The file is a reference list of all chain message type URLs. It is **not** loaded by any Go code in this repository — it ships as static data for downstream consumers and tooling that need a canonical list of injectable message types. |
| 104 | + |
| 105 | +### `injective_data/ofac.json` |
| 106 | + |
| 107 | +This file contains a snapshot of OFAC-sanctioned and restricted wallet addresses sourced from the [injective-lists](https://github.com/InjectiveLabs/injective-lists) repository. To refresh it: |
| 108 | + |
| 109 | +```bash |
| 110 | +make update-ofac-list |
| 111 | +``` |
| 112 | + |
| 113 | +This target delegates to `examples/chain/ofac/1_DownloadOfacList/example.go`, which calls `chainclient.DownloadOfacList()` — the same function used at runtime in `NewOfacChecker()`. The download URL and output path are defined once in [`client/chain/ofac.go`](client/chain/ofac.go). |
| 114 | + |
| 115 | +The committed copy in the repository is a snapshot used for offline use and initial setup. At runtime, `NewOfacChecker()` checks whether the file exists on disk and downloads a fresh copy automatically if it is missing — so `make update-ofac-list` is only needed when you want to explicitly update the committed snapshot. |
| 116 | + |
| 117 | +--- |
| 118 | + |
| 119 | +## 5. Running tests and lint |
| 120 | + |
| 121 | +After regenerating exchange bindings or chain types, run the test and lint suites to confirm nothing is broken. |
| 122 | + |
| 123 | +### Tests |
| 124 | + |
| 125 | +```bash |
| 126 | +make tests |
| 127 | +``` |
| 128 | + |
| 129 | +Runs `go test -race ./client/... ./ethereum/...` after clearing the test cache. |
| 130 | + |
| 131 | +To collect a coverage profile: |
| 132 | + |
| 133 | +```bash |
| 134 | +make coverage |
| 135 | +``` |
| 136 | + |
| 137 | +Writes `coverage.out` in atomic mode for the same packages. |
| 138 | + |
| 139 | +### Lint |
| 140 | + |
| 141 | +The lint targets all run `golangci-lint` with a 15-minute timeout. They differ only in which baseline revision they compare against, controlling how much of the codebase is checked: |
| 142 | + |
| 143 | +- `make lint` — reports only findings new since the `dev` branch (default for PR work). |
| 144 | +- `make lint-last-commit` — reports findings new since `HEAD~` (just the last commit). |
| 145 | +- `make lint-master` — reports findings new since the `master` branch. |
| 146 | +- `make lint-all` — runs the linter against the entire repository with no baseline (use for full audits or after bulk regenerations). |
| 147 | + |
| 148 | +`golangci-lint` must be installed locally; all four targets export `GOPROXY=direct` before running. |
| 149 | + |
| 150 | +--- |
| 151 | + |
| 152 | +## 6. Release update checklist |
| 153 | + |
| 154 | +1. **Edit `Makefile`** — update the `-b <tag>` flag in both `clone-injective-indexer` and `clone-injective-core` to the new release tag (see [section 1](#1-configuring-the-upstream-versions-do-this-first)). |
| 155 | +2. **Update Exchange bindings** — `make copy-exchange-client` |
| 156 | +3. **Update chain types and proto** — `make copy-chain-types` (also regenerates `chain_messages_list.json`) |
| 157 | +4. **Sync `go.mod`** — align dependency versions in [go.mod](go.mod) with `injective-core`'s `go.mod` for the target tag, then run `go mod tidy` (see [section 3](#syncing-gomod)). |
| 158 | +5. **Verify** — `make tests && make lint` |
| 159 | +6. **Refresh OFAC list** (optional) — `make update-ofac-list` |
| 160 | +7. **Commit** all changed files, including `chain/`, `exchange/`, `proto/`, `go.mod`, `go.sum`, `injective_data/chain_messages_list.json`, and `Makefile`. |
0 commit comments