diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 471d64146b..e626018946 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,9 +12,9 @@ For more complex conversations, use the [discussions](https://github.com/unionla We evaluate the need for a PR based on: -1. Severity of the issue (bug or feature request). -2. Maintainability: will this become a burden for little gain, or add value? -3. Can the core team understand the code additions being made, and maintain them, or will they rely on you in the future? +1. Severity of the issue (bug or feature request), +1. Maintainability: will this become a burden for little gain, or add value? +1. Can the core team understand the code additions being made, and maintain them, or will they rely on you in the future? ## Working on a PR diff --git a/README.md b/README.md index 9d0d4c350b..38b34486e7 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@
- +
- [![built with garnix](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Funionlabs%2Funion%3Fbranch%3Dmain)](https://garnix.io) - [![Docs](https://img.shields.io/badge/docs-main-blue)][docs] - [![Discord badge][]](https://discord.union.build) - [![Twitter handle][]][Twitter badge] +[![built with garnix](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Funionlabs%2Funion%3Fbranch%3Dmain)](https://garnix.io) +[![Docs](https://img.shields.io/badge/docs-main-blue)][docs] +[![Discord badge]](https://discord.union.build) +[![Twitter handle]][twitter badge]
@@ -82,29 +82,29 @@ Check the `#developers` channel on [Union's discord](https://discord.union.build The official docs are hosted [here][docs]. Each individual component also has accompanying developer documentation for contributors, which you can find in each `README.md`. -[docs]: https://docs.union.build "Official Union Docs" -[IBC]: https://github.com/cosmos/ibc "cosmos/ibc" -[Discord badge]: https://img.shields.io/discord/1158939416870522930?logo=discord -[Twitter handle]: https://img.shields.io/twitter/follow/union_build.svg?style=social&label=Follow -[Twitter badge]: https://twitter.com/intent/follow?screen_name=union_build -[CosmWasm]: https://cosmwasm.com/ -[Arbitrum]: https://github.com/OffchainLabs/arbitrum -[Ethereum]: https://ethereum.org -[EVM]: https://ethereum.org/en/developers/docs/evm/ -[Rust]: https://www.rust-lang.org/ -[Solidity]: https://soliditylang.org/ -[Go]: https://go.dev/ -[TypeScript]: https://www.typescriptlang.org/ -[Svelte]: https://svelte.dev -[Astro]: https://astro.build -[`CometBLS`]: https://github.com/unionlabs/cometbls -[Light Clients]: https://a16zcrypto.com/posts/article/an-introduction-to-light-clients/ -[Gnark]: https://github.com/ConsenSys/gnark -[Nix]: https://zero-to-nix.com/ -[NixOS]: https://nixos.org -[OrbStack]: https://orbstack.dev/ -[Consensus Verification]: https://union.build/docs/concepts/consensus-verification/ -[union.build]: https://union.build [app.union.build]: https://app.union.build [app.union.build/faucet]: https://app.union.build/faucet -[Cosmos]: https://cosmos.network +[arbitrum]: https://github.com/OffchainLabs/arbitrum +[astro]: https://astro.build +[consensus verification]: https://union.build/docs/concepts/consensus-verification/ +[cosmos]: https://cosmos.network +[cosmwasm]: https://cosmwasm.com/ +[discord badge]: https://img.shields.io/discord/1158939416870522930?logo=discord +[docs]: https://docs.union.build "Official Union Docs" +[ethereum]: https://ethereum.org +[evm]: https://ethereum.org/en/developers/docs/evm/ +[gnark]: https://github.com/ConsenSys/gnark +[go]: https://go.dev/ +[ibc]: https://github.com/cosmos/ibc "cosmos/ibc" +[light clients]: https://a16zcrypto.com/posts/article/an-introduction-to-light-clients/ +[nix]: https://zero-to-nix.com/ +[nixos]: https://nixos.org +[orbstack]: https://orbstack.dev/ +[rust]: https://www.rust-lang.org/ +[solidity]: https://soliditylang.org/ +[svelte]: https://svelte.dev +[twitter badge]: https://twitter.com/intent/follow?screen_name=union_build +[twitter handle]: https://img.shields.io/twitter/follow/union_build.svg?style=social&label=Follow +[typescript]: https://www.typescriptlang.org/ +[union.build]: https://union.build +[`cometbls`]: https://github.com/unionlabs/cometbls diff --git a/VERSIONING.md b/VERSIONING.md index 4871333142..a9092149e0 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -31,6 +31,7 @@ The Union testnet will track the most recent release candidate. Release candidat The Union mono-repo is made up of many different components that are maintained and updated at different rates. We've opted to release components individually rather than in all encompassing versions. To do this, version tags are to now be made in the form of `/v{X}.{Y}.{Z}` (`voyager-v0.2.1`). This will enable us to quickly update and distribute various components without creating monolithic releases. To create a release: + - Checkout a new branch from main (or desired commit) with a name in the form of `release//v{X}.{Y}.{Z}`. - On this branch, create the first release candidate tag in the form `/v{X}.{Y}.{Z}-rc1`. - Continue iterating release candidate tags until a viable release is generated diff --git a/app/README.md b/app/README.md index 722da007cb..071c314961 100644 --- a/app/README.md +++ b/app/README.md @@ -1,6 +1,6 @@ # Union's Web App -[app.union.build](https://app.union.build) is built to be user friendly, extremely reliable, and blazing fast. It achieves this through a stack of optimized tools that do most processing at compile time (before you even use the app), and by connecting to our optimized [hubble](../hubble) indexer. +[app.union.build](https://app.union.build) is built to be user friendly, extremely reliable, and blazing fast. It achieves this through a stack of optimized tools that do most processing at compile time (before you even use the app), and by connecting to our optimized [hubble](../hubble) indexer. ## Quickstart @@ -18,18 +18,18 @@ nix run .#app-fetch-schema ## Architecture -It's a [SvelteKit] app that compiles to a static site such that it can later be distributed using decentralized providers like [IPFS]. -Data is fetched from [graphql.union.build]. The [GraphQL] queries are defined in `./src/lib/graphql/documents`, and types for it are generated by [gql.tada]. We use [TanStack Query] to periodically fetch new data (both for [GraphQL] and REST). +It's a [SvelteKit] app that compiles to a static site such that it can later be distributed using decentralized providers like [IPFS]. +Data is fetched from [graphql.union.build]. The [GraphQL] queries are defined in `./src/lib/graphql/documents`, and types for it are generated by [gql.tada]. We use [TanStack Query] to periodically fetch new data (both for [GraphQL] and REST). For interacting with EVM chains, we use [Wagmi & Viem](https://wagmi.sh/core/getting-started). For interacting with Cosmos chains, we use [CosmJS]. The basis for our components are generated by [shadcn-svelte](https://www.shadcn-svelte.com), and then modified to adhere to our brand guidelines. Styling is done using [Tailwind]. -[SvelteKit]: https://kit.svelte.dev/ -[GraphQL]: https://graphql.org -[TanStack Query]: https://tanstack.com/query/latest/docs/framework/svelte/overview -[graphql.union.build]: https://graphql.union.build +[cosmjs]: https://github.com/cosmos/cosmjs [gql.tada]: https://github.com/0no-co/gql.tada -[IPFS]: https://ipfs.tech -[CosmJS]: https://github.com/cosmos/cosmjs -[Tailwind]: https://tailwindcss.com +[graphql]: https://graphql.org +[graphql.union.build]: https://graphql.union.build +[ipfs]: https://ipfs.tech +[sveltekit]: https://kit.svelte.dev/ +[tailwind]: https://tailwindcss.com +[tanstack query]: https://tanstack.com/query/latest/docs/framework/svelte/overview diff --git a/app/src/lib/abi/README.md b/app/src/lib/abi/README.md new file mode 100644 index 0000000000..bb44c81bb1 --- /dev/null +++ b/app/src/lib/abi/README.md @@ -0,0 +1,20 @@ +These abis are made by running `nix build .#hubble-abis`, and then applying the following transformation in order to get viem typechecking: + +1. Update file from .json to .ts format. For example, myAbi.json should be myAbi.ts, +1. Add export and const assertion + +```diff +-[ ++ export const myAbi = [ + { + "inputs": [{ "name": "owner", "type": "address" }], + "name": "balanceOf", + "outputs": [{ name: "balance", type: "uint256" }], + "stateMutability": "view", + "type": "function", + } +-] ++] as const +``` + +source: https://github.com/wevm/wagmi/discussions/1084#discussioncomment-3891592 diff --git a/docs/src/content/docs/concepts/bls-signatures.mdx b/docs/src/content/docs/concepts/bls-signatures.mdx new file mode 100644 index 0000000000..bd602fcc8a --- /dev/null +++ b/docs/src/content/docs/concepts/bls-signatures.mdx @@ -0,0 +1,12 @@ +--- +title: BLS Signatures +--- + +Boneh–Lynn–Shacham (BLS) signatures form the foundation of [CometBLS](/docs/architecture/cometbls). They are cheaper to verify for both regular [IBC](/docs/concepts/ibc) and zero-knowledge proof (ZKP) based IBC. With BLS signatures, we can aggregate the public keys and the signatures and verify the aggregated signature with the aggregated private key. BLS signature aggregation has a few advantages: + +- Transaction size decreases compared to ECDSA verification. We do not need to transfer all signatures, just the aggregate. +- On-chain computation cost decreases. Instead of verifying each signature, we verify the aggregate. +- Zkp verification is much more efficient. +- State growth is significantly reduced. + +Note that the Union validators do not produce zkps directly. This function is performed by [galois](/docs/architecture/cometbls). Relayers can produce proofs or use Union as a distributed sequencing layer through proof claims. diff --git a/evm/README.md b/evm/README.md index 6b1834c4f2..3850b5fdbd 100644 --- a/evm/README.md +++ b/evm/README.md @@ -53,6 +53,7 @@ Note that the addresses are different because we often redeploy without upgradin Production contracts will get solely upgraded through the proxy and have the same addresses accross networks. ### Sepolia + - Deployer: [0x12cffF5aAd6Fc340BBE6F1fe674C5Aa78f0d1E0F](https://sepolia.etherscan.io/address/0x12cffF5aAd6Fc340BBE6F1fe674C5Aa78f0d1E0F) - Sender: [0x2c077908e1173ff1a6097ca9e2af547c1e5130c4](https://sepolia.etherscan.io/address/0x2c077908e1173ff1a6097ca9e2af547c1e5130c4) - IBCHandler: [0xa390514f803a3b318b93bf6cd4beeb9f8299a0eb](https://sepolia.etherscan.io/address/0xa390514f803a3b318b93bf6cd4beeb9f8299a0eb) @@ -62,6 +63,7 @@ Production contracts will get solely upgraded through the proxy and have the sam - Multicall: [0x70BEDecc56C7104e410c1e4c25FcA0bcd29A0bA9](https://sepolia.etherscan.io/address/0x70bedecc56c7104e410c1e4c25fca0bcd29a0ba9) ### Berachain + - Deployer: [0x17425b7d2d97E613dE2ADa01Dc472F76879E08Fe](https://bartio.beratrail.io/address/0x17425b7d2d97E613dE2ADa01Dc472F76879E08Fe) - Sender: [0x27156Eb671984304ae75Da49aD60C4479B490A06](https://bartio.beratrail.io/address/0x27156Eb671984304ae75Da49aD60C4479B490A06) - IBCHandler: [0x851c0EB711fe5C7c8fe6dD85d9A0254C8dd11aFD](https://bartio.beratrail.io/address/0x851c0EB711fe5C7c8fe6dD85d9A0254C8dd11aFD) @@ -71,6 +73,7 @@ Production contracts will get solely upgraded through the proxy and have the sam - Multicall: [0x3147CA8f531070DDAC1b93700ef18E4Dd05b86ec](https://bartio.beratrail.io/address/0x3147CA8f531070DDAC1b93700ef18E4Dd05b86ec) ### Arbitrum + - Deployer: [0x7d00b15A53B8b14a482BF761653532F07b7DcBdE](https://sepolia.arbiscan.io/address/0x7d00b15A53B8b14a482BF761653532F07b7DcBdE) - Sender: [0x50C9C35e0197e781e9aD7a3F6baDD8d01E45c377](https://sepolia.arbiscan.io/address/0x50C9C35e0197e781e9aD7a3F6baDD8d01E45c377) - IBCHandler: [0xb599bfcfb9D4fCaE9f8aB5D45d9A6F145E6b7573](https://sepolia.arbiscan.io/address/0xb599bfcfb9D4fCaE9f8aB5D45d9A6F145E6b7573) diff --git a/flake.nix b/flake.nix index 7006896fc8..56b5221559 100644 --- a/flake.nix +++ b/flake.nix @@ -647,11 +647,15 @@ meta.mainProgram = "forge"; }; }; + mdformat = { + enable = true; + package = unstablePkgs.mdformat; + }; }; settings = { global = { hidden = true; - excludes = [ ".git/**" "**/vendor/**" "**/.sqlx/**" "uniond/docs/static/**" ]; + excludes = [ ".git/**" "**/vendor/**" "**/.sqlx/**" "uniond/docs/static/**" ".github/**/*.md" ]; }; }; }; diff --git a/galoisd/README.md b/galoisd/README.md index f09f66ca3a..c35a2b352e 100644 --- a/galoisd/README.md +++ b/galoisd/README.md @@ -31,7 +31,6 @@ docker pull ghcr.io/unionlabs/galoisd: `nix run github:unionlabs/union/#galoisd -- --help` - ## Architecture Galoisd exposes gRPC endpoints to generate and verify CometBLS zero-knowledge proofs. @@ -88,14 +87,15 @@ let public_input = sha256( Where `header` represents the new block header to verify and `trusted_validators_hash` is the `next_validators_hash` of the previously verified header. Furthermore, we truncate the most significant byte to fit the BN254 scalar field. In the circuit, we proceed as follows: + - Recalculate the public input hash from the private inputs and verify that it matches the public input 31-byte hash. - Recalculate the block hash. - Hash the block hash to a G2 point on the BN254 curve, using [RFC -9380](https://www.rfc-editor.org/rfc/rfc9380.html). + 9380](https://www.rfc-editor.org/rfc/rfc9380.html). - Verify that 1/3 of `trusted_validators_hash` have signed (recalculate and verify the validators hash, -aggregate public keys and verify signature). + aggregate public keys and verify signature). - Verify that 2/3 of `header.validators_hash` have signed (recalculate and verify the validators hash, -aggregate public keys and verify signature). + aggregate public keys and verify signature). Note that both signatures verified in-circuit must be computed by the caller. @@ -127,4 +127,3 @@ sequenceDiagram Client->>Galois: VerifyRequest Galois->>Client: VerifyResponse ``` - diff --git a/lib/ics23/README.md b/lib/ics23/README.md index ba17d1cdcf..89359bbae3 100644 --- a/lib/ics23/README.md +++ b/lib/ics23/README.md @@ -4,47 +4,47 @@ Below an overview of all data types from the [ICS-23 specification](https://gith ## CommitmentState -spec: `object` +spec: `object`\ impl: _not implemented_ ## CommitmentRoot -spec: `object` +spec: `object`\ impl: `[u8]` ## CommitmentPath -spec: `object` +spec: `object`\ impl: `[u8]` ## CommitmentPrefix -spec: `object` +spec: `object`\ impl: _not implemented_ ### applyPrefix -spec: `applyPrefix = (prefix: CommitmentPrefix, path: CommitmentPath) => CommitmentPath` +spec: `applyPrefix = (prefix: CommitmentPrefix, path: CommitmentPath) => CommitmentPath`\ impl: _not implemented_ ### removePrefix -spec: `removePrefix = (prefix: CommitmentPrefix, path: commitmentPath) => Path` +spec: `removePrefix = (prefix: CommitmentPrefix, path: commitmentPath) => Path`\ impl: _not implemented_ ## Path -spec: `string` +spec: `string`\ impl: `[u8]` ## Value -spec: `[]byte` +spec: `[]byte`\ impl: `[u8]` ## CommitmentProof -spec: `object` +spec: `object`\ impl: - `existence_proof.rs (from lib/unionlabs) # ExistenceProof` @@ -52,38 +52,38 @@ impl: ### generate -spec: `(initial: Map) => CommitmentState` +spec: `(initial: Map) => CommitmentState`\ impl: _not implemented_ ### calculateRoot -spec: `(state: CommitmentState) => CommitmentRoot` -impl: _not implemented_. +spec: `(state: CommitmentState) => CommitmentRoot`\ +impl: _not implemented_.\ (NOTE: `existence_proof.rs # calculate_root` seems to do this, but it has an `ExistenceProof` as argument, not a `CommitmentState`) ### set -spec: `(state: CommitmentState, path: Path, value: Value) => CommitmentState` +spec: `(state: CommitmentState, path: Path, value: Value) => CommitmentState`\ impl: _not implemented_ ### remove -spec `(state: CommitmentState, path: Path) => CommitmentState` +spec `(state: CommitmentState, path: Path) => CommitmentState`\ impl: _not implemented_ ### createMembershipProof -spec: `(state: CommitmentState, path: CommitmentPath, value: Value) => CommitmentProof` +spec: `(state: CommitmentState, path: CommitmentPath, value: Value) => CommitmentProof`\ impl: _not implemented_ ### createNonMembershipProof -spec: `(state: CommitmentState, path: CommitmentPath) => CommitmentProof` +spec: `(state: CommitmentState, path: CommitmentPath) => CommitmentProof`\ impl: _not implemented_ ### verifyMembership -spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath, value: Value) => boolean` +spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath, value: Value) => boolean`\ impl: ```rust @@ -99,7 +99,7 @@ verify_membership( ### verifyNonMembership -spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath) => boolean` +spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath) => boolean`\ impl: ```rust @@ -115,10 +115,10 @@ verify_membership( ### batchVerifyMembership (optional) -spec: `(root: CommitmentRoot, proof: CommitmentProof, items: Map) => boolean` +spec: `(root: CommitmentRoot, proof: CommitmentProof, items: Map) => boolean`\ impl: _not implemented_ ### batchVerifyNonMembership (optional) -spec: `(root: CommitmentRoot, proof: CommitmentProof, paths: Set) => boolean` +spec: `(root: CommitmentRoot, proof: CommitmentProof, paths: Set) => boolean`\ impl: _not implemented_ diff --git a/light-clients/ethereum-light-client/ARCHITECTURE.md b/light-clients/ethereum-light-client/ARCHITECTURE.md index 259f5f7c60..f3407a1952 100644 --- a/light-clients/ethereum-light-client/ARCHITECTURE.md +++ b/light-clients/ethereum-light-client/ARCHITECTURE.md @@ -4,9 +4,9 @@ Our [Ethereum](https://ethereum.org/) light client is a CosmWasm smart contract To see how this is integrated within `uniond`, see [uniond/ARCHITECTURE.md](../../uniond/ARCHITECTURE.md). We decided on implementing the light client as a smart contract instead of a native module because: 1. Native modules require chain-upgrade if we want to introduce the native client or update it. But the wasm light client can be uploaded and modified through governance. -2. `08-wasm` module already implements the generic client module and it only calls the underlying smart contract for the chain-specific parts like membership verification +1. `08-wasm` module already implements the generic client module and it only calls the underlying smart contract for the chain-specific parts like membership verification update validation, etc. This makes the implementation very clean and we don't have to implement any boilerplate code at all. -3. This generic client implementation can be easily adapted into different ecosystems that support wasm smart contracts. +1. This generic client implementation can be easily adapted into different ecosystems that support wasm smart contracts. We also implemented [ethereum-verifier](https://github.com/unionlabs/union/tree/main/lib/ethereum-verifier) to verify updates and commitments in the Ethereum side. We closely followed the [official consensus specs](https://github.com/ethereum/consensus-specs) from Ethereum. diff --git a/uniond/README.md b/uniond/README.md index 908f9752e5..b9dea8f2f3 100644 --- a/uniond/README.md +++ b/uniond/README.md @@ -26,7 +26,7 @@ When running `uniond` in production, we recommend using [`unionvisor`](../unionv ## Architecture -Uniond is a [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) based blockchain consisting of a set of modules. +Uniond is a [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) based blockchain consisting of a set of modules. ```mermaid graph LR @@ -50,7 +50,7 @@ graph LR end ``` -The most notable module is **x/ibc**, as it contains [08-wasm](https://ibc.cosmos.network/main/ibc/light-clients/wasm/overview/). This allows us to write +The most notable module is **x/ibc**, as it contains [08-wasm](https://ibc.cosmos.network/main/ibc/light-clients/wasm/overview/). This allows us to write **Light Clients** in [Rust](https://www.rust-lang.org/), compile them to [WebAssembly](https://webassembly.org/), and upload them to the `uniond` chain to support many ecosystems. You can find the light clients [here](../light-clients). diff --git a/unionvisor/README.md b/unionvisor/README.md index d2926ee48b..12e2a2e0a9 100644 --- a/unionvisor/README.md +++ b/unionvisor/README.md @@ -1,7 +1,5 @@ - - # Unionvisor Unionvisor is a utility for managing [`uniond`](../uniond) deployments. It manages upgrade lifecycles and integrates well with NixOS. diff --git a/voyager/README.md b/voyager/README.md index 766ec92195..2fe4cd33db 100644 --- a/voyager/README.md +++ b/voyager/README.md @@ -4,14 +4,14 @@ Relaying is hard. There are several key properties to a reliable relayer, the mo which being: - **Speed.** IBC Relaying is a race to the bottom, with many relayers fighting to be the first to -submit a packet, often times submitting a packet that ends up being frontrun. + submit a packet, often times submitting a packet that ends up being frontrun. - **Data Integrity.** There's no use being the first to submit a packet if the packet is submitted -incorrectly, and a good relayer will never drop packets. The latter is especially important for -ordered channels, as a channel will be closed if a packet on it times out. + incorrectly, and a good relayer will never drop packets. The latter is especially important for + ordered channels, as a channel will be closed if a packet on it times out. - **Quick Startup Times.** RPCs are unreliable, and it's incredibly difficult to build around every -possible failure case - especially when connecting to multiple different chains. Even with proper -error handling and retry logic, in the event of a crash, startup time should be miniscule (see: -) + possible failure case - especially when connecting to multiple different chains. Even with proper + error handling and retry logic, in the event of a crash, startup time should be miniscule (see: + ) Voyager takes a novel approach to solving these problems. Internally, everything is modeled as a finite state machine, which is stored in postgres to ensure transactional integrity. Every chain