diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d1a266..9d50c33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,7 @@ Thank you for your interest in contributing to Lafiya! Lafiya is an open-source This repository holds the Soroban (Stellar) smart contracts. Because Lafiya is a multi-repo ecosystem, contributions here often have ripple effects across other repositories. This guide outlines the setup, conventions, and workflows required to contribute safely. -- Rust (stable), installed via [rustup](https://rustup.rs) -- The `wasm32v1-none` target: `rustup target add wasm32v1-none` -- `pre-commit` (required for local git hooks): Install via `pip install pre-commit` or `brew install pre-commit`, then run `pre-commit install` in the repository root. +See [Local Setup > Prerequisites](#prerequisites) for the tools you'll need before contributing. ## Table of Contents - [Local Setup](#local-setup) diff --git a/bindings/attestation-registry/README.md b/bindings/attestation-registry/README.md index e4c7562..1cf2257 100644 --- a/bindings/attestation-registry/README.md +++ b/bindings/attestation-registry/README.md @@ -1,15 +1,14 @@ # attestation-registry JS -JS library for interacting with [Soroban](https://soroban.stellar.org/) smart contract `attestation-registry` via Soroban RPC. +This is the generated TypeScript client for the Lafiya `attestation-registry` Soroban contract, which stores and verifies patient attestation records. It lets JS/TS consumers (e.g. `lafiya-web`) call the contract's methods via Soroban RPC without hand-writing the XDR encoding/decoding. It is the counterpart to [`bindings/attester-registry`](../attester-registry), which manages the allowlist of addresses permitted to submit these attestations. -This library was automatically generated by Soroban CLI using a command similar to: +This library was automatically generated using the project's `make bindings` target, which runs: ```bash -soroban contract bindings ts \ - --rpc-url INSERT_RPC_URL_HERE \ - --network-passphrase "INSERT_NETWORK_PASSPHRASE_HERE" \ - --contract-id INSERT_CONTRACT_ID_HERE \ - --output-dir ./path/to/attestation-registry +stellar contract bindings typescript \ + --wasm target/wasm32v1-none/release/attestation_registry.wasm \ + --output-dir bindings/attestation-registry \ + --overwrite ``` The network passphrase and contract ID are exported from [index.ts](./src/index.ts) in the `networks` constant. If you are the one who generated this library and you know that this contract is also deployed to other networks, feel free to update `networks` with other valid options. This will help your contract consumers use this library more easily. @@ -28,13 +27,7 @@ But you don't need to publish this library to NPM to use it. You can add it to y However, we've actually encountered [frustration](https://github.com/stellar/soroban-example-dapp/pull/117#discussion_r1232873560) using local libraries with NPM in this way. Though it seems a bit messy, we suggest generating the library directly to your `node_modules` folder automatically after each install by using a `postinstall` script. We've had the least trouble with this approach. NPM will automatically remove what it sees as erroneous directories during the `install` step, and then regenerate them when it gets to your `postinstall` step, which will keep the library up-to-date with your contract. -```json -"scripts": { - "postinstall": "soroban contract bindings ts --rpc-url INSERT_RPC_URL_HERE --network-passphrase \"INSERT_NETWORK_PASSPHRASE_HERE\" --id INSERT_CONTRACT_ID_HERE --name attestation-registry" -} -``` - -Obviously you need to adjust the above command based on the actual command you used to generate the library. +To regenerate this library after contract changes, run `make bindings` from the repository root (see the `bindings` target in the [Makefile](../../Makefile)). # Use it diff --git a/bindings/attester-registry/README.md b/bindings/attester-registry/README.md index c9c6d33..95cefd0 100644 --- a/bindings/attester-registry/README.md +++ b/bindings/attester-registry/README.md @@ -1,15 +1,14 @@ # attester-registry JS -JS library for interacting with [Soroban](https://soroban.stellar.org/) smart contract `attester-registry` via Soroban RPC. +This is the generated TypeScript client for the Lafiya `attester-registry` Soroban contract, which manages the allowlist of addresses permitted to submit attestations. It lets JS/TS consumers (e.g. `lafiya-web`) call the contract's methods via Soroban RPC without hand-writing the XDR encoding/decoding. -This library was automatically generated by Soroban CLI using a command similar to: +This library was automatically generated using the project's `make bindings` target, which runs: ```bash -soroban contract bindings ts \ - --rpc-url INSERT_RPC_URL_HERE \ - --network-passphrase "INSERT_NETWORK_PASSPHRASE_HERE" \ - --contract-id INSERT_CONTRACT_ID_HERE \ - --output-dir ./path/to/attester-registry +stellar contract bindings typescript \ + --wasm target/wasm32v1-none/release/attester_registry.wasm \ + --output-dir bindings/attester-registry \ + --overwrite ``` The network passphrase and contract ID are exported from [index.ts](./src/index.ts) in the `networks` constant. If you are the one who generated this library and you know that this contract is also deployed to other networks, feel free to update `networks` with other valid options. This will help your contract consumers use this library more easily. @@ -28,13 +27,7 @@ But you don't need to publish this library to NPM to use it. You can add it to y However, we've actually encountered [frustration](https://github.com/stellar/soroban-example-dapp/pull/117#discussion_r1232873560) using local libraries with NPM in this way. Though it seems a bit messy, we suggest generating the library directly to your `node_modules` folder automatically after each install by using a `postinstall` script. We've had the least trouble with this approach. NPM will automatically remove what it sees as erroneous directories during the `install` step, and then regenerate them when it gets to your `postinstall` step, which will keep the library up-to-date with your contract. -```json -"scripts": { - "postinstall": "soroban contract bindings ts --rpc-url INSERT_RPC_URL_HERE --network-passphrase \"INSERT_NETWORK_PASSPHRASE_HERE\" --id INSERT_CONTRACT_ID_HERE --name attester-registry" -} -``` - -Obviously you need to adjust the above command based on the actual command you used to generate the library. +To regenerate this library after contract changes, run `make bindings` from the repository root (see the `bindings` target in the [Makefile](../../Makefile)). # Use it diff --git a/docs/releasing.md b/docs/releasing.md index 4626ed4..fa3182b 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -65,7 +65,7 @@ every `v*.*.*` tag; see ADR-0009 "Follow-up" for what remains before it is load- Because Soroban smart contracts are immutable once deployed (unless an upgrade path is explicitly programmed), deploying a new version generally requires deploying new WASM bytecode and updating the contract addresses referenced by downstream consumers (such as the frontend app `lafiya-web`). -For details on the redeployment, initialization, and upgrade state migration processes, please cross-reference the **upgrade-runbook issue** on GitHub: -- [Upgrade Runbook Issue #48 (GitHub)](https://github.com/Lafiya-xyz/Lafiya-contract/issues/48) +For details on the redeployment, initialization, and upgrade state migration processes, please cross-reference the upgrade runbook: +- [Contract Upgrade Runbook](runbooks/contract-upgrade.md) Always follow the instructions in the runbook when performing redeployments to ensure that downstream services are not interrupted.