From d73f496668e7802a2a2273214dcd15417a2d400f Mon Sep 17 00:00:00 2001
From: Spoorthi Satheesha <9302666+spoo-bar@users.noreply.github.com>
Date: Tue, 1 Oct 2024 14:52:34 +0530
Subject: [PATCH 1/2] Update readme.md
---
readme.md | 187 +++++++++++++++---------------------------------------
1 file changed, 50 insertions(+), 137 deletions(-)
diff --git a/readme.md b/readme.md
index 5169be5e..7776f0b5 100644
--- a/readme.md
+++ b/readme.md
@@ -1,66 +1,56 @@
![Noble banner](https://raw.githubusercontent.com/noble-assets/networks/main/Twitter_Banner.png)
# ✨✨ Noble ✨✨
-## Overview
+[Noble](https://noble.xyz/) is a Cosmos [application-specific blockchain](https://docs.cosmos.network/v0.50/learn/intro/why-app-specific) purpose-built for native asset issuance. Noble brings the efficiency and interoperability of native assets to the wider Cosmos ecosystem, supporting [Circle's USDC](https://www.circle.com/en/usdc), [Ondo's USDY](https://ondo.finance/), [Monerium's EURe](https://monerium.com/). Noble’s vision is to be the world’s premier issuance hub for digital assets that connect to other blockchains seamlessly. Noble leverages the Cosmos-SDK – a flexible toolkit that allows developers to leverage existing modules, and to seamlessly integrate custom modules that add virtually unlimited functionality for asset issuers onthe Noble blockchain.
-[Noble](https://nobleassets.xyz/) is a Cosmos [application-specific blockchain](https://docs.cosmos.network/v0.46/intro/why-app-specific.html) purpose-built for native asset issuance. Noble brings the efficiency and interoperability of native assets to the wider Cosmos ecosystem, starting with USDC. Noble’s vision is to be the world’s premier issuance hub for digital assets that connect to other blockchains seamlessly. Noble leverages the Cosmos-SDK – a flexible toolkit that allows developers to leverage existing modules, and to seamlessly integrate custom modules that add virtually unlimited functionality for asset issuers onthe Noble blockchain.
+[![twitter](https://img.shields.io/badge/twitter-@noble_xyz-white?labelColor=0f1331&style=flat)](https://twitter.com/noble_xyz/) [![telegram](https://img.shields.io/badge/telegram-noble-white?labelColor=0f1331&style=flat)](https://t.me/+5mCog0PAWCRmOWYx) [![website](https://img.shields.io/badge/website-noble.xyz-white?labelColor=0f1331&style=flat)](https://noble.xyz/)
-## Noble App-Chain Design
+## Contents
+1. [Noble Chain Design](#noble-chain-design)
+2. [Assets on Noble](#assets-on-noble)
+3. [Protocol Features](#protocol-features)
+4. [Noble on the Interchain](#noble-on-the-interchain)
+5. [Noble Upgrades and Governance](#noble-upgrades--governance)
+6. [For Developers](#for-developers)
+7. [For Node Operators & Validators](#for-node-operators--validators)
+8. [Contributing](#contributing)
-The Noble app-chain conforms to [industry standard](https://github.com/centrehq/centre-tokens/blob/master/doc/tokendesign.md) smart contracting capabilities with regards to asset issuance functionality. This functionality allows the minting and burning of tokens by multiple entities and the freezing blacklisting of addresses on the Noble chain.
+## Noble Chain Design
-Key authorities include:
+The Noble protocol runs on Proof-of-Authority consensus with a trusted validator set. The validator set is permissioned by equal shares of staking tokens placed in vesting accounts. The tokens have no value. Economic security is derived from fees captured by the chain as issued assets on a block-by-block basis. If a double sign is detected by the chain, the validator address will be “tombstoned”, meaning that their tokens and the address will no longer be usable for validation and resulting in the loss of all future fee revenue. The Proof-of-Authority model provides real economic cost to faulty validator behavior and thus provides economic security to the network that can be computed in real time based on past and projected fees.
-**Owner:** The Owner role has the ability to reassign all roles and will be held by the asset issuer.
-
-**Minter:** The Owner has the authority to add/remove Minters which have the authority to both mint and burn tokens on the Noble chain.
-
-**Blacklist:** The asset issuer has the authority to blacklist addresses. A blacklisted address will be unable to transfer tokens outside of the Noble chain via IBC, or to approve, mint, or burn tokens.
-
-
-## Tokenfactory
-
-Noble implements a tokenfactory module pattern to enable the minting of generic assets in Cosmos. Further, tokenfactory modules are under the exclusive purview of the asset issuers and are separate and distinct from governance of the Noble chain. Additionally, each tokenfactory module is distinct from one other as they each house unique access controls with ownership over the minting and burning of a specific asset.
-
-The Access Control table below shows the functionality tied to each privileged account.
-
-## Access Control
+Noble intends to monitor developments in shared security across the blockchain ecosystem to ensure the optimality of the security model.
-| | **Owner** | **Minter** | **Master Minter** | **Minter Controller** | **Pauser** | **Blacklister** | **Is Paused
(Actions Allowed)** |
-|---------------------------------------------|:---------:|:----------:|:-----------------:|:---------------------:|:----------:|:---------------:|:--------------------------------:|
-| **Blacklist** | | | | | | x | x |
-| **Unblacklist** | | | | | | x | x |
-| **Burn** | | x | | | | | |
-| **Mint** | | x | | | | | |
-| **Add Minter Controller** | | | x | | | | x |
-| **Add Minter with allowance** | | | | x | | | x |
-| **Pause** | | | | | x | | x |
-| **Unpause** | | | | | x | | x |
-| **Remove Minter Controller** | | | x | | | | x |
-| **Remove Minter** | | | | x | | | x |
-| **Update Blacklister** | x | | | | | | x |
-| **Update Master Minter** | x | | | | | | x |
-| **Update Owner** | x | | | | | | x |
-| **Update Pauser** | x | | | | | | x |
-| **Transer Tokens (tokenfactory asset)** | x | x | x | x | x | x | |
-| **Transer Tokens (non-tokenfactory asset)** | x | x | x | x | x | x | x |
+## Assets on Noble
+Every asset issued on the Noble chain is implemented as its own Cosmos SDK module.
-## Security Guarantees in a Permissioned Validator Set (Proof of Authority)
+| Issuer | Asset | Module Name |
+| ---------------------------------------- | ----- | ---------------------- |
+| [Circle](https://www.circle.com/en/usdc) | USDC | [noble-fiattokenfactory](https://github.com/circlefin/noble-fiattokenfactory) |
+| [Ondo](https://ondo.finance/) | USDY | [aura](https://github.com/ondoprotocol/usdy-noble) |
+| [Monerium](https://monerium.com/) | EURe | [florin](https://github.com/monerium/module-noble) |
+| [Hashnote](https://www.hashnote.com/) | USYC | [halo](https://github.com/noble-assets/halo) |
-The initial plans for Noble’s go-to-market entailed leveraging Replicated Security (also known as ["Interchain Security”](https://github.com/cosmos/interchain-security)) – the shared security model of the Cosmos Hub. This feature allows validators to secure app-chains using the value of ATOMs staked by Cosmos Hub delegators. Due to uncertainty around the design of replicated security (e.g., the removal of automated slashing packets), Noble has paused integration with Replicated Security.
+## Protocol features
-At launch, Noble will be a Proof of Authority chain with a trusted validator set (a subset of Cosmos Hub validators). The validator set will be permissioned by equal shares of staking tokens placed in vesting accounts. The tokens will have no value. Economic security will derive from fees captured by the chain in USDC and other assets on a block-by-block basis. If a double sign is detected by the chain, the validator address will be “tombstoned,” meaning that their tokens and the address will no longer be usable for validation and resulting in the loss of all future fee revenue. The Proof of Authority model provides real economic cost to faulty validator behavior and thus provides economic security to the network that can be computed in real time based on past and projected fees.
+Along with asset issuance, the Noble protocol also implements the following modules:
-Noble intends to monitor developments in shared security across the blockchain ecosystem to ensure the optimality of the security model.
+| Module name | Features |
+| ------------------------------------------------------------------------ | -------- |
+| [noble-cctp](https://github.com/circlefin/noble-cctp) | Allows native transfer of Circle's USDC across ecosystems through their [Cross Chain Transfer Protocol](https://www.circle.com/en/cross-chain-transfer-protocol) |
+| [forwarding](https://github.com/noble-assets/forwarding) | Allows a custom account type on Noble to auto forward any tokens it receives to an address on a different chain connected via IBC |
+| [globalfee](./x/globalfee) | Allows the protocol to control the transaction fees and bypass gas fees for specific sdk.Msg types |
+| [tariff](./x/tariff) | Adds a source of revenue for the protocol as well as its contributors by collecting a percentage of share of token transfers via Noble |
+| [paramauthority](https://github.com/strangelove-ventures/paramauthority) | Allows a configured address to perform the governance operations. [More](#noble-upgrades--governance) |
-## Connecting to Noble
+## Noble on the Interchain
App-chains are able to permissionlessly connect to Noble [via IBC](https://medium.com/the-interchain-foundation/eli5-what-is-ibc-def44d7b5b4c), a universal interoperability protocol that allows two different blockchains to communicate with one another, garaunteeing reliable, ordered, and authenticated communication.
-How to integrate with Noble?
+#### How to integrate with Noble?
-To establish a connection to Noble (or any 2 IBC compatible chains), developers will be required to set up a relayer on an existing path. This [tutorial](https://github.com/cosmos/relayer/blob/main/docs/create-path-across-chain.md) gives an overview of how to create a channel, client, and connection and to start relaying IBC packets.
+To establish a connection to Noble (or any 2 IBC compatible chains), anybody can set up a relayer on an existing path. This [tutorial](https://github.com/cosmos/relayer/blob/main/docs/create-path-across-chain.md) gives an overview of how to create a channel, client, and connection and to start relaying IBC packets.
## Noble Upgrades & Governance
@@ -96,113 +86,36 @@ The NMM is a 5/7 multisig for passing a Noble Multisig proposal to fulfill the t
Stakeholders on the NMM will be able to be rotated in and out of the mulitisg over time.
-## Partnership with StrangeLove & Future Technical Development
-
-Noble has selected StrangeLove Labs (“StrangeLove”) as its initial engineering and product partner to implement Noble’s initial app-chain design. StrangeLove has built an MVP and is bringing it to market using battle-proven XP-derived practices like Test-driven Development, Continuous Integration and Continuous Deployment, and short iteration cycles.
-
-In collaboration with StrangeLove, Noble intends to build an in-house team focused on software development and integration to further build the Noble vision related to products and services.
-
-## Media
-
-TWITTER: [@noble_xyz](https://twitter.com/noble_xyz/)
-
-WEB: [nobleassets.xyz](https://nobleassets.xyz/)
-
+## For Developers
-## Build and install to go bin path
+### Setup Noble locally
-[go](https://go.dev/dl/) will be needed for this install
+The following software should be installed on the target system:
+
+1. Go Programming Language (https://go.dev)
+2. Git (https://git-scm.com)
+3. GNU Make (https://www.gnu.org/software/make)
```
+git clone https://github.com/noble-assets/noble
+cd noble
make install
```
-## Initialize config
+### Local Running
-Come up with a moniker for your node, then run:
+To quickly spin up a standalone noble chain and setup all privileged accounts, run the [play.sh](play.sh) bash script
```
-nobled init $MONIKER
+sh play.sh
```
-Prior to launch, some config settings are required by the `tokenfactory` module in the `genesis.json` file:
-- There must be a designated address for the "owner" role.
-- Other roles, such as `masterMinter`, `blacklister`, and `pauser` are optional at genesis.
-- `mintingDenom` must be filled out and the `denom` specified must be registered in `denom_metadata`
-
-`tokenfactory `Example:
-```json
-"tokenfactory": {
- "params": {},
- "blacklistedList": [],
- "paused": {
- "paused": false
- },
- "masterMinter": {
- "address": "noble1x8rynykqla7cnc0tf2f3xn0wa822ztt70y39vn"
- },
- "mintersList": [],
- "pauser": {
- "address": "noble1g3v4qdc83h6m5wdz3x92vfu0tjtt7e6y48qqrz"
- },
- "blacklister": {
- "address": "noble159leclhhuhhcmedu2n8nfjjedxjyrtkee8l4v2"
- },
- "owner": {
- "address": "noble153eyy4uufmrak2swgrn4fjtyslg256ecdngyve"
- },
- "minterControllerList": [],
- "mintingDenom": {
- "denom": "urupee"
- }
- }
-```
+## For Node Operators & Validators
-`denom_metadata` example:
-
-```json
-"denom_metadata": [
- {
- "display": "rupee",
- "base": "urupee",
- "name": "rupee",
- "symbol": "rupee",
- "denom_units": [
- {
- "denom": "urupee",
- "aliases": [
- "microrupee"
- ],
- "exponent": "0"
- },
- {
- "denom": "mrupee",
- "aliases": [
- "milirupee"
- ],
- "exponent": "3"
- },
- {
- "denom": "rupee",
- "aliases": null,
- "exponent": "6"
- }
- ]
- },
- ]
-```
-## Launch node
-
-```
-nobled start
-```
-
-## Running Nodes
+### Running Nodes
- See [`noble-networks`](https://github.com/noble-assets/networks/tree/main) for all info around validating for mainnet and testent
-## Testing
-
-The [`interchaintest`](https://github.com/strangelove-ventures/interchaintest) test suite has been imported into the noble repo. Tests can be ran and written [here](./interchaintest/).
+## Contributing
-To quickly spin up a standalone noble chain and setup all privileged accounts, run the [play.sh](play.sh) bash script.
+This repository is not looking for external contributors.
\ No newline at end of file
From a0d54cc3b6a26893213fdcef81a18049195bb7ee Mon Sep 17 00:00:00 2001
From: John Letey
Date: Thu, 31 Oct 2024 12:50:00 +0100
Subject: [PATCH 2/2] fix: implement review feedback
---
.github/README.md | 106 +++++++++++++++++++++++++++++++++++++++
.github/banner.png | Bin 0 -> 120285 bytes
Twitter_Banner.png | Bin 378092 -> 0 bytes
readme.md | 121 ---------------------------------------------
4 files changed, 106 insertions(+), 121 deletions(-)
create mode 100644 .github/README.md
create mode 100644 .github/banner.png
delete mode 100644 Twitter_Banner.png
delete mode 100644 readme.md
diff --git a/.github/README.md b/.github/README.md
new file mode 100644
index 00000000..d3bdc04e
--- /dev/null
+++ b/.github/README.md
@@ -0,0 +1,106 @@
+![](banner.png)
+
+# ✨✨ Noble ✨✨
+
+[Noble](https://noble.xyz) is a Cosmos [application-specific blockchain](https://docs.cosmos.network/v0.50/learn/intro/why-app-specific) purpose-built for native asset issuance. Noble brings the efficiency and interoperability of native assets to the wider Cosmos ecosystem, supporting [Circle's USDC](https://www.circle.com/en/usdc), [Ondo's USDY](https://ondo.finance/usdy), [Monerium's EURe](https://monerium.com), and [Hashnote's USYC](https://usyc.hashnote.com). Noble's vision is to be the world's premier issuance hub for digital assets that connect to other blockchains seamlessly. Noble leverages the Cosmos SDK – a flexible toolkit that allows developers to leverage existing modules, and to seamlessly integrate custom modules that add virtually unlimited functionality for asset issuers on the Noble blockchain.
+
+[![twitter](https://img.shields.io/badge/twitter-@noble__xyz-white?labelColor=black)](https://twitter.com/noble_xyz) [![website](https://img.shields.io/badge/website-noble.xyz-white?labelColor=black)](https://noble.xyz)
+
+## Contents
+1. [Noble Chain Design](#noble-chain-design)
+2. [Assets on Noble](#assets-on-noble)
+3. [Protocol Features](#protocol-features)
+4. [Noble on the Interchain](#noble-on-the-interchain)
+5. [Noble Upgrades and Governance](#noble-upgrades--governance)
+6. [For Developers](#for-developers)
+7. [For Node Operators & Validators](#for-node-operators--validators)
+
+## Noble Chain Design
+
+The Noble chain runs on Proof-of-Authority consensus with a trusted validator set. The validator set is permissioned by equal shares of staking tokens placed in permanently locked vesting accounts. The tokens have no value. Economic security is derived from fees captured by the chain on a block-by-block basis. If a double sign is detected by the chain, the validator address will be "tombstoned", meaning that their token and address will no longer be usable for validation and resulting in the loss of all future fee revenue. The Proof-of-Authority model provides real economic cost to faulty validator behavior and thus provides economic security to the network that can be computed in real time based on past and projected fees.
+
+The Noble Core Team intends to monitor developments in shared security across various ecosystems to ensure the optimality of our security model.
+
+## Assets on Noble
+
+Every asset issued on the Noble chain is implemented as its own dedicated Cosmos SDK module.
+
+| Issuer | Asset | Module Name |
+|--------------------------------------|-------|---------------------------------------------------------------------------|
+| [Circle](https://www.circle.com) | USDC | [`fiattokenfactory`](https://github.com/circlefin/noble-fiattokenfactory) |
+| [Ondo](https://ondo.finance) | USDY | [`aura`](https://github.com/ondoprotocol/usdy-noble) |
+| [Monerium](https://monerium.com) | EURe | [`florin`](https://github.com/monerium/module-noble) |
+| [Hashnote](https://www.hashnote.com) | USYC | [`halo`](https://github.com/noble-assets/halo) |
+
+## Protocol Features
+
+Along with asset issuance, the Noble chain also implements the following modules:
+
+| Module Name | Description |
+|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`cctp`](https://github.com/circlefin/noble-cctp) | Allows native transfers of Circle's stablecoins across ecosystems through their [Cross Chain Transfer Protocol](https://www.circle.com/en/cross-chain-transfer-protocol). |
+| [`forwarding`](https://github.com/noble-assets/forwarding) | Allows specific accounts to be created to allow users to interact with IBC via a native bank transfer. |
+| [`globalfee`](https://github.com/noble-assets/globalfee) | Allows Noble's governance to control transaction fees and certain transactions that can bypass this. |
+| [`authority`](https://github.com/noble-assets/authority) | Allows the Noble Maintenance Multisig to perform governance actions on specific modules. [More](#noble-upgrades--governance). |
+
+## Noble on the Interchain
+
+App-chains are able to permissionlessly connect to Noble [via IBC](https://medium.com/the-interchain-foundation/eli5-what-is-ibc-def44d7b5b4c), a universal interoperability protocol that allows two different blockchains to communicate with one another, guaranteeing reliable, ordered, and authenticated communication.
+
+### How to integrate with Noble?
+
+To establish a connection to Noble (or any 2 IBC compatible chains), anybody can set up a relayer on an existing path. This [tutorial](https://github.com/cosmos/relayer/blob/main/docs/create-path-across-chain.md) gives an overview of how to create a channel, client, and connection and to start relaying IBC packets.
+
+## Noble Upgrades & Governance
+
+The Noble chain is governed by the Noble Maintenance Multisig (or "NMM"). The NMM is a 5/7 multisig, who's members include the Noble corporate entity and core ecosystem partners. A key objective of the NMM is to achieve a reasonable level of geographic diversity for governance resilience. The current multisig members are listed below:
+
+- Binary Holdings: Switzerland
+- Chorus One: Switzerland
+- Cosmostation: Korea
+- Iqlusion: USA
+- Luganodes: Switzerland
+- Noble (the organization): Canada
+- Strangelove: USA
+
+The NMM is given the following key responsibilities:
+
+**Upgrade Authority**
+
+The NMM has an on-chain procedure to instruct validators to coordinate a halt of the protocol running the Noble chain at a specific block height, to then restart the blockchain with a new version. Importantly, validators always have discretionary authority to follow those instructions. If 1/3 + 1 of the voting power on the Noble chain refuses to follow these upgrade instructions, the chain halts.
+
+**Parameter Changes**
+
+The NMM has the ability to initiate parameter changes. This authority is distinct from the upgrade functionality as it would not require the Noble validators to run a new chain binary. A parameter change is automatically be introduced into the state machine of the Noble chain.
+
+**IBC Maintenance**
+
+The NMM has the ability to both re-establish IBC connections that have expired and sever them in case of an emergency. Any such action related to an IBC connection is achieved automatically upon execution by the multisig.
+
+## For Developers
+
+### Installing Noble Locally
+
+The following software is a prerequisite to installing Noble:
+
+1. Go Programming Language (https://go.dev)
+2. Git (https://git-scm.com)
+3. GNU Make (https://www.gnu.org/software/make)
+
+```
+git clone https://github.com/noble-assets/noble
+cd noble
+make install
+```
+
+### Running a Local Network
+
+To quickly spin up a standalone Noble chain locally and setup all privileged accounts, run the [local.sh](local.sh) script:
+
+```
+sh local.sh -r
+```
+
+## For Node Operators & Validators
+
+See our [`networks`](https://github.com/noble-assets/networks) repository for all information around running Noble for mainnet and testnet!
diff --git a/.github/banner.png b/.github/banner.png
new file mode 100644
index 0000000000000000000000000000000000000000..e0109d8cf2ec1e6f6731981428445c422dca3bf9
GIT binary patch
literal 120285
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