A comprehensive smart contract suite built with Golang and Gnolang, a deterministic, purpose-built Go variant for blockchains

# Gno

[![License](https://img.shields.io/badge/license-GNO%20GPL%20v5-blue.svg)](LICENSE.md)
[![Go Reference](https://pkg.go.dev/badge/hey/google)](https://gnolang.github.io/gno/github.com/gnolang/gno.html)

> At first, there was Bitcoin, out of entropy soup of the greater All.
> Then, there was Ethereum, which was created in the likeness of Bitcoin,
> but made Turing complete.
>
> Among these were Tendermint and Cosmos to engineer robust PoS and IBC.
> Then came Gno upon Cosmos and there spring forth Gnoland,
> simulated by the Gnomes of the Greater Resistance.

**Gno is a blockchain platform that interprets a deterministic variant of Go 
for writing smart contracts, built on Tendermint consensus.**

Gno is an interpreted and fully-deterministic implementation of the Go
programming language, designed to build succinct and composable smart contracts.
The first blockchain to use it is gno.land, a contribution-based chain, backed
by a variation of the [Tendermint](./tm2) consensus engine.

PLEASE NOTE: This is NOT the same project or token as the excellent Gnosis.io project.

## Getting Started

Explore Gno through our comprehensive documentation:

- **[For Users](./docs#use-gnoland)** - Learn how to use Gno applications, 
  manage accounts, and interact with the blockchain
- **[For Builders](./docs#build-on-gnoland)** - Start writing smart contracts, 
  understand the Gno language, and deploy your applications  
- **[Resources](./docs#resources)** - Technical specifications, best 
  practices, and advanced topics

Visit [gno.land](https://gno.land) to see live smart contracts in action.

## Key Features

- **Go Syntax**: If you know Go, you know Gno
- **Deterministic Execution**: Fully predictable contract behavior
- **Composable Packages**: Import and reuse code like regular Go
- **Auto-Persisted State**: Global variables automatically saved between calls
- **Contribution System**: Rewarding open source contributors
- **Developer Experience**: Comprehensive tooling including testing, 
  debugging, and hot-reload development

## Documentation

- [Documentation](./docs/) - Complete documentation portal
- [Examples](./examples) - Sample contracts and patterns
- [Go API Reference](https://gnolang.github.io/gno/github.com/gnolang/gno.html) - 
  Go package documentation

## Gno Playground
<a href="https://play.gno.land/p/VxDC6AmKmK6?run.expr=println(Render(%22%22))">
  <img alt="play.gno.land" src="https://img.shields.io/badge/Play-Hello_World-691a00.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCAxNTggMTU4Ij48cGF0aCBkPSJtMTU2IDItNiA1LTIgMmE1NCA1NCAwIDAgMS0yNCAxMmwtMyAxaC00Yy02IDAtOS0xLTE1LTNhNjIgNjIgMCAwIDAtMzUtNmgtMWwtNCAxYTYzIDYzIDAgMCAwLTUwIDY4bDEgMmEyNyAyNyAwIDAgMCAwIDRsNiAxNWEzMyAzMyAwIDAgMSAyIDIxIDYyIDYyIDAgMCAxLTMgOCA2MSA2MSAwIDAgMS0xMyAyMGwtMyA0LTEgMWgxbDEtMmEyMDYgMjA2IDAgMCAxIDYtNWwyLTJhODggODggMCAwIDAgOC03bDEtMSAyLTIgMy0zYTY2MSA2NjEgMCAwIDEgMjYtMjRsNjItNjIgNC00IDMtMyAyLTMgOS05IDMtMyAyLTMgNi02IDExLTEzIDMtMyAxLTEtMSAxWk03OSAyNWM5IDEgMTcgNCAyMyA4IDQgMiA1IDQgNSA3bC0xIDMtMSAydjFsLTItMmE0MSA0MSAwIDAgMC0zNC0xMCA0MyA0MyAwIDAgMC0zMyAyNyA0OSA0OSAwIDAgMC0zIDIwIDMxIDMxIDAgMCAwIDEgNWwyIDRjMSA1IDQgOSA3IDEzbDIgMnYxbC01IDEtNC0xYy0yLTEtNS01LTctMTBsLTEtMmE2MSA2MSAwIDAgMS0zLTEzIDY2IDY2IDAgMCAxIDAtMTRjMS01IDMtMTEgNi0xNmE1MyA1MyAwIDAgMSA0MC0yNmg4Wm0yIDEzaDFsMTEgMyAxMCA4djRMNzkgNzhsLTI2IDI1Yy0yIDEtNCAxLTYtMWwtNS03YTQwIDQwIDAgMCAxLTUtMTljMC04IDMtMTYgOC0yM2w5LThhNDEgNDEgMCAwIDEgMTktOGw4IDFabTQ0IDEzLTMgNnY3YTIyMSAyMjEgMCAwIDEgMiAxNGwtMSAxMGE0NiA0NiAwIDAgMS01NyAzNWgtOWMtMyAwLTcgMi03IDNsNCAyYTU3IDU3IDAgMCAwIDMyIDVoM2wzLTFhNTUgNTUgMCAwIDAgMzQtODJsLTEgMVoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNMTEzIDU5Yy0xIDItMiA0LTEgNmwxIDNhMzggMzggMCAwIDEtNDggNDRoLTRsLTMgMmE0NCA0NCAwIDAgMCAxMCAzaDE1YTQyIDQyIDAgMCAwIDMxLTU4aC0xWiIgZmlsbD0iI2ZmZiIvPjwvc3ZnPg==" />
</a>
</br></br>

[Gno Playground](https://play.gno.land), available at 
[play.gno.land](https://play.gno.land), is a web app that allows users to 
write, share, and deploy Gno code. Developers can seamlessly test, debug, and 
deploy realms and packages on gno.land, while being able to collaborate with 
peers to work on projects together and seek assistance. A key feature of Gno 
Playground is the ability to get started without the need to install any tools 
or manage any services, offering immediate access and convenience for users.

**Note:** The playground may not always reflect the latest changes in this 
repository.

## Repository Structure

* [docs](./docs) - Official documentation
* [examples](./examples) - Smart contract examples and guides
* [gnovm](./gnovm) - GnoVM and the Gno language
* [gno.land](./gno.land) - Blockchain node and tools
* [tm2](./tm2) - Tendermint2 consensus engine
* [contribs](./contribs) - Additional tools and utilities
* [misc](./misc) - Various utilities and scripts

## Community

**Explore the Ecosystem:**
- [Gnoverse](https://github.com/gnoverse) - Community projects and initiatives
- [Awesome Gno](https://github.com/gnoverse/awesome-gno) - Curated list of 
  resources
- [Gnoscan](https://gnoscan.io) - Blockchain explorer
- [Gno Studio](https://gno.studio) - Web IDE for Gno development
- [Become a Gnome](./docs/builders/become-a-gnome.md) - Join the contributor 
  community

**Connect & Get Help:**
- [Discord](https://discord.gg/YFtMjWwUN7) - Real-time support and development 
  discussions
- [Twitter](https://twitter.com/_gnoland) - Official announcements and updates
- [YouTube](https://www.youtube.com/@_gnoland) - Tutorials, workshops, and 
  development calls
- [Workshops](https://github.com/gnolang/workshops) - Educational materials
- [Reddit](https://www.reddit.com/r/gnoland) - Forum-style discussions
- [Telegram](https://t.me/gnoland) - Community-run group

**Contribute:**
- [GitHub Issues](https://github.com/gnolang/gno/issues) - Report bugs and 
  request features
- [Contributing Guide](./CONTRIBUTING.md) - Guidelines for contributors


<details><summary>CI/CD/Tools badges and links</summary>

  GitHub Actions:

  * [![gno.land](https://github.com/gnolang/gno/actions/workflows/gnoland.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/gnoland.yml)
  * [![gnovm](https://github.com/gnolang/gno/actions/workflows/gnovm.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/gnovm.yml)
  * [![tm2](https://github.com/gnolang/gno/actions/workflows/tm2.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/tm2.yml)
  * [![examples](https://github.com/gnolang/gno/actions/workflows/examples.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/examples.yml)
  * [![docker](https://github.com/gnolang/gno/actions/workflows/docker.yml/badge.svg)](https://github.com/gnolang/gno/actions/workflows/docker.yml)

  Codecov:

  * General: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4)](https://codecov.io/gh/gnolang/gno)
  * tm2: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=tm2)](https://codecov.io/gh/gnolang/gno/tree/master/tm2)
  * gnovm: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=gnovm)](https://codecov.io/gh/gnolang/gno/tree/master/gnovm)
  * gno.land: [![codecov](https://codecov.io/gh/gnolang/gno/branch/master/graph/badge.svg?token=HPP82HR1P4&flag=gno.land)](https://codecov.io/gh/gnolang/gno/tree/master/gno.land)
  * examples: TODO

  Go Report Card:

  * [![Go Report Card](https://goreportcard.com/badge/github.com/gnolang/gno)](https://goreportcard.com/report/github.com/gnolang/gno)
  * tm2, gnovm, gno.land: TODO (blocked by tm2 split, because we need go mod workspaces)

  Pkg.go.dev

  * [![Go Reference](https://pkg.go.dev/badge/hey/google)](https://gnolang.github.io/gno/github.com/gnolang/gno.html) \
    (pkg.go.dev will not show our repository as it has a license it doesn't recognise)
</details>



A Framework for Building Public Blockchains in the Cosmos Ecosystem

<div align="left">
  <h1> Cosmos SDK </h1>
</div>

![banner](docs/static/img/banner.svg)

<div align="center">
  <a href="https://github.com/cosmos/cosmos-sdk/blob/main/LICENSE">
    <img alt="License: Apache-2.0" src="https://img.shields.io/github/license/cosmos/cosmos-sdk.svg" />
  </a>
  <a href="https://pkg.go.dev/github.com/cosmos/cosmos-sdk">
    <img src="https://pkg.go.dev/badge/github.com/cosmos/cosmos-sdk.svg" alt="Go Reference">
  </a>
  <a href="https://goreportcard.com/report/github.com/cosmos/cosmos-sdk">
    <img alt="Go report card" src="https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk" />
  </a>
</div>
<div align="center">
  <a href="https://discord.com/invite/interchain">
    <img alt="Discord" src="https://img.shields.io/discord/669268347736686612.svg" />
  </a>
  <a href="https://sourcegraph.com/github.com/cosmos/cosmos-sdk?badge">
    <img alt="Imported by" src="https://sourcegraph.com/github.com/cosmos/cosmos-sdk/-/badge.svg" />
  </a>
</div>

The Cosmos SDK is a modular, open-source blockchain SDK for building secure, high-performance Layer 1 chains with full customizability used by 200+ chains in production.   Developers can use the Cosmos SDK to easily and quickly spin up custom blockchains that can natively interoperate.

The Cosmos SDK is tailored for building secure, sovereign application-specific blockchains. Developers building with the Cosmos SDK can use predefined modules that cover standard blockchain functionality or create custom modules for their specific use case. This composable architecture enables robust customization. The SDK provides abstractions for permissioning, governance, state management, account abstraction, tokenization processes, application logic, and more.

Cosmos SDK blockchains get interoperability out-of-the-box via a native integration with the [Inter-Blockchain Communication Protocol (IBC)](https://github.com/cosmos/ibc-go). ibc-go is implemented as a Go module in the Cosmos SDK. 

While the Cosmos SDK is plug-and-play with any consensus engine, we recommend using [CometBFT](https://github.com/cometbft/cometbft) for a fast, battle-tested, high-throughput, configurable BFT state machine. CometBFT is developed as part of the Cosmos Stack and its releases are updated alongside the SDK.

**WARNING**: The Cosmos SDK has mostly stabilized, but we are still making some breaking changes.

## Quick Start

To learn how the Cosmos SDK works from a high-level perspective, see the Cosmos SDK [High-Level Intro](https://docs.cosmos.network/main/intro/overview).

If you want to get started quickly and learn how to build on top of Cosmos SDK, visit [Cosmos SDK Tutorials](https://tutorials.cosmos.network). You can also fork the tutorial's repository to get started building your own Cosmos SDK application.

Note: We advise to always use the latest maintained [Go version](https://go.dev/dl/) for building Cosmos SDK applications.

## Modules

The Cosmos SDK maintains a set of modules that can be included in your blockchain application.  For more information
on modules, see our [introduction doc](./x/README.md).

## Enterprise Modules

In addition to the core SDK modules, we maintain enterprise-grade modules designed for specialized use cases such as permissioned networks and consortium chains. These modules are located in the `enterprise/` directory and have different licensing terms than the core SDK.

## Maintainers
[Cosmos Labs](https://cosmoslabs.io/) maintains the core components of the stack: Cosmos SDK, CometBFT, IBC, Cosmos EVM, and various developer tools and frameworks. The detailed maintenance policy can be found [here](https://github.com/cosmos/security/blob/main/POLICY.md). In addition to developing and maintaining the Cosmos Stack, Cosmos Labs provides advisory and engineering services for blockchain solutions. [Get in touch with Cosmos Labs](https://www.cosmoslabs.io/contact).

Cosmos Labs is a wholly-owned subsidiary of the [Interchain Foundation](https://interchain.io/), the Swiss nonprofit responsible for treasury management, funding public goods, and supporting governance for Cosmos. 

The Cosmos Stack is supported by a robust community of open-source contributors. 

## History
The Cosmos SDK was first released in 2019, and the first blockchain to use the SDK in production was the [Cosmos Hub](https://hub.cosmos.network/main). Today, the Cosmos SDK is a popular, battle-tested, open-source framework used by hundreds of chains.

The Cosmos Hub still receives the most up-to-date Cosmos SDK versions. The Cosmos Hub application, `gaia`, has its own [cosmos/gaia repository](https://github.com/cosmos/gaia). 

## Developer Community and Support

The issue list of this repo is exclusively for bug reports and feature requests. We have active, helpful communities on Discord, Telegram, and Slack.

**| Need Help? | Support & Community: [Discord](https://discord.com/invite/interchain) - [Telegram](https://t.me/CosmosOG) - [Talk to an Expert](https://cosmos.network/interest-form) - [Join the #Cosmos-tech Slack Channel](https://forms.gle/A8jawLgB8zuL1FN36) |**

## Documentation and Resources
**View the Cosmos SDK documentation: https://docs.cosmos.network/**

### Cosmos Stack Libraries

- [CometBFT](https://github.com/cometbft/cometbft) - High-performance, 10k+ TPS configurable BFT consensus engine.
- [The Inter-Blockchain Communication Protocol (IBC)](https://github.com/cosmos/ibc-go/) - A blockchain interoperability protocol that allows blockchains to transfer any type of data encoded in bytes.
- [Cosmos EVM](https://github.com/cosmos/evm) - Native EVM layer for Cosmos SDK chains. 

## Disambiguation

This Cosmos SDK project is not related to the [React-Cosmos](https://github.com/react-cosmos/react-cosmos) project (yet). Many thanks to Evan Coury and Ovidiu (@skidding) for this Github organization name. As per our agreement, this disambiguation notice will stay here.


cosmos-sdk

A distributed, Byzantine fault-tolerant, deterministic state machine replication engine. It is a fork of Tendermint Core and implements the Tendermint consensus algorithm

<div align="left">
  <h1> CometBFT </h1>
</div>

![banner](docs/imgs/banner.svg)

[![Version][version-badge]][version-url]
[![Go version][go-badge]][go-url]
[![Discord chat][discord-badge]][discord-url]
[![License][license-badge]][license-url]
[![Sourcegraph][sg-badge]][sg-url]

CometBFT is the most widely-adopted, battle-tested consensus engine in blockchain today. It is a [Byzantine Fault Tolerant (BFT)](https://en.wikipedia.org/wiki/Byzantine_fault) middleware that takes a state transition machine - written in any programming language - and securely replicates it on many machines.

CometBFT is highly performant and achieves speeds of up to 10k transactions per second (TPS). Its flagship feature, ABCI++ enables developers to add programmability and customization to every step of the consensus engine.

Developers can use CometBFT for BFT state machine replication of applications written in any programming language and development environment. This modularity gives developers flexibility to choose tools and technologies best suited for specific projects, improves maintainability, and delivers the scalability required for large-scale decentralized applications.

CometBFT is a fork of [Tendermint Core][tm-core] and implements the Tendermint consensus algorithm.

## Releases

Please do not depend on `main` as your production branch. Use [releases](https://github.com/cometbft/cometbft/releases) instead.

More on how releases are conducted can be found [here](./RELEASES.md).


## Minimum requirements

| CometBFT version | Requirement | Notes             |
|------------------|-------------|-------------------|
| main             | Go version  | Go 1.23 or higher |
| v0.38.x          | Go version  | Go 1.22 or higher |

### Install

See the [install guide](./docs/guides/install.md).

### Quick Start

- [Single node](./docs/guides/quick-start.md)
- [Local cluster using docker-compose](./docs/networks/docker-compose.md)

## Versioning

### Semantic Versioning

CometBFT uses [Semantic Versioning](http://semver.org/) to determine when and
how the version changes.

To provide some stability to users of 0.X.X versions of CometBFT, the MINOR
version is used to signal breaking changes across CometBFT's API. This API
includes all publicly exposed types, functions, and methods in non-internal Go
packages as well as the types and methods accessible via the CometBFT RPC
interface.

Breaking changes to these public APIs will be documented in the CHANGELOG.

### Upgrades

In an effort to avoid accumulating technical debt, we do not
guarantee that breaking changes (i.e. bumps in the MINOR version) will work with
existing CometBFT blockchains. In these cases you will have to start a new
blockchain, or write something custom to get the old data into the new chain.
However, any bump in the PATCH version should be compatible with existing
blockchain histories.

For more information on upgrading, see [UPGRADING.md](./UPGRADING.md).

### Supported Versions

Currently supported versions include:

- v0.38.x: CometBFT v0.38 introduces ABCI 2.0, which implements the entirety of
  ABCI++


## Developer Community and Support

The issue list of this repo is exclusively for bug reports and feature requests. We have active, helpful communities on Discord, Telegram, and Slack.

**| Need Help? | Support & Community: [Discord](https://discord.com/invite/interchain) - [Telegram](https://t.me/CosmosOG) - [Talk to an Expert](https://cosmos.network/interest-form) - [Join the #Cosmos-tech Slack Channel](https://forms.gle/A8jawLgB8zuL1FN36) |**

## Security

To report a security vulnerability, see the Cosmos [bug bounty program](https://hackerone.com/cosmos). For examples of the kinds of bugs we're looking for, see [our security policy](SECURITY.md).

## Maintainers
[Cosmos Labs](https://cosmoslabs.io/) maintains the core components of the stack: Cosmos SDK, CometBFT, IBC, Cosmos EVM, and various developer tools and frameworks. The detailed maintenance policy can be found [here](https://github.com/cosmos/security/blob/main/POLICY.md). In addition to developing and maintaining the Cosmos Stack, Cosmos Labs provides advisory and engineering services for blockchain solutions. [Get in touch with Cosmos Labs](https://www.cosmoslabs.io/contact).

Cosmos Labs is a wholly-owned subsidiary of the [Interchain Foundation](https://interchain.io/), the Swiss nonprofit responsible for treasury management, funding public goods, and supporting governance for Cosmos.

The Cosmos Stack is supported by a robust community of open-source contributors.

## Contributing

If you are interested in working on an issue, please comment on it, and take a look at the [contributing guidelines](./CONTRIBUTING.md). We welcome and appreciate community contributions!

## Documentation and Resources

### Documentation
- [CometBFT Documentation](https://docs.cometbft.com/v0.38/)
- [CometBFT Specification](./spec/README.md)
- [Documentation](./docs/)

### Cosmos Stack Libraries

- [Cosmos SDK](http://github.com/cosmos/cosmos-sdk) - A framework for building
  applications in Golang
- [The Inter-Blockchain Communication Protocol (IBC)](https://github.com/cosmos/ibc-go/) - A blockchain interoperability protocol that allows blockchains to transfer any type of data encoded in bytes.
- [Cosmos EVM](https://github.com/cosmos/evm) - Native EVM layer for Cosmos SDK chains.

### Research

Below are links to the original Tendermint consensus algorithm and relevant
whitepapers which CometBFT will continue to build on.

- [The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938)
- [Master's Thesis on Tendermint](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769)
- [Original Whitepaper: "Tendermint: Consensus Without Mining"](https://tendermint.com/static/docs/tendermint.pdf)



[bft]: https://en.wikipedia.org/wiki/Byzantine_fault_tolerance
[smr]: https://en.wikipedia.org/wiki/State_machine_replication
[Blockchain]: https://en.wikipedia.org/wiki/Blockchain
[version-badge]: https://img.shields.io/github/v/release/cometbft/cometbft.svg
[version-url]: https://github.com/cometbft/cometbft/releases/latest
[api-badge]: https://camo.githubusercontent.com/915b7be44ada53c290eb157634330494ebe3e30a/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f676f6c616e672f6764646f3f7374617475732e737667
[api-url]: https://pkg.go.dev/github.com/cometbft/cometbft
[go-badge]: https://img.shields.io/badge/go-1.22-blue.svg
[go-url]: https://github.com/moovweb/gvm
[discord-badge]: https://img.shields.io/discord/669268347736686612.svg
[discord-url]: https://discord.gg/interchain
[license-badge]: https://img.shields.io/github/license/cometbft/cometbft.svg
[license-url]: https://github.com/cometbft/cometbft/blob/main/LICENSE
[sg-badge]: https://sourcegraph.com/github.com/cometbft/cometbft/-/badge.svg
[sg-url]: https://sourcegraph.com/github.com/cometbft/cometbft?badge
[tests-url]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml
[tests-url-v038x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.38.x
[tests-url-v037x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.37.x
[tests-url-v034x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml?query=branch%3Av0.34.x
[tests-badge]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=main
[tests-badge-v038x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.38.x
[tests-badge-v037x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.37.x
[tests-badge-v034x]: https://github.com/cometbft/cometbft/actions/workflows/tests.yml/badge.svg?branch=v0.34.x
[lint-badge]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=main
[lint-badge-v034x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.34.x
[lint-badge-v037x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.37.x
[lint-badge-v038x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml/badge.svg?branch=v0.38.x
[lint-url]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml
[lint-url-v034x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.34.x
[lint-url-v037x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.37.x
[lint-url-v038x]: https://github.com/cometbft/cometbft/actions/workflows/lint.yml?query=branch%3Av0.38.x
[tm-core]: https://github.com/tendermint/tendermint


cometbft

<div align="center">
  <img alt="Gossamer logo" src="/docs/docs/assets/img/gossamer_banner.png" width="600" />
</div>
<div align="center">
  <a href="https://www.gnu.org/licenses/gpl-3.0">
    <img alt="License: GPL v3" src="https://img.shields.io/badge/License-GPLv3-blue.svg?style=for-the-badge&label=License" height="20"/>
  </a>
    <a href="https://github.com/ChainSafe/gossamer/actions">
    <img alt="build status" src="https://img.shields.io/github/actions/workflow/status/ChainSafe/gossamer/build.yml?branch=development&style=for-the-badge&logo=github&label=build" height="20"/>
  </a>
  <a href="https://godoc.org/github.com/ChainSafe/gossamer">
    <img alt="go doc" src="http://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge" height="20" />
  </a>
  <a href="https://goreportcard.com/report/github.com/ChainSafe/gossamer">
    <img alt="go report card" src="https://goreportcard.com/badge/github.com/ChainSafe/gossamer?style=for-the-badge" height="20" />
  </a>
</div>
<div align="center">
  <a href="https://app.codecov.io/gh/ChainSafe/gossamer">
    <img alt="Test Coverage" src="https://img.shields.io/codecov/c/github/ChainSafe/gossamer/development?style=for-the-badge" height="20" />
  </a>
    <a href="https://discord.gg/zy8eRF7FG2">
    <img alt="Discord" src="https://img.shields.io/discord/593655374469660673.svg?style=for-the-badge&label=Discord&logo=discord" height="20"/>
  </a>
  <a href="https://medium.com/chainsafe-systems/tagged/polkadot">
    <img alt="Gossamer Blog" src="https://img.shields.io/badge/Medium-grey?style=for-the-badge&logo=medium" height="20" />
  </a>
    <a href="https://medium.com/chainsafe-systems/tagged/polkadot">
    <img alt="Twitter" src="https://img.shields.io/twitter/follow/chainsafeth?color=blue&label=follow&logo=twitter&style=for-the-badge" height="20"/>
  </a>
</div>
<br />

> **Warning**
>
> The Gossamer Polkadot Host is pre-production software [2022-12-01]

>Developed by [ChainSafe](https://chainsafe.io) and funded by a Web3 Foundation grant and Polkadot [Treasury proposals](https://polkadot.polkassembly.io/treasury/808?tab=description).
>

Gossamer is a [Golang](https://go.dev/) implementation of the
[Polkadot Host](https://wiki.polkadot.network/docs/learn-polkadot-host): an
execution environment for the Polkadot runtime, which is materialized as a Web
Assembly (Wasm) blob. In addition to running an embedded Wasm executor, a
Polkadot Host must orchestrate a number of interrelated services, such as
[networking](dot/network/README.md), block production, block finalization, a
JSON-RPC server, [and more](cmd/gossamer/README.md#client-components).


## Getting Started

To get started with Gossamer, follow the steps below to build the source code
and start a development network.

### Prerequisites

[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is required
to acquire the Gossamer source code, and
[Make](https://tilburgsciencehub.com/building-blocks/configure-your-computer/automation-and-workflows/make/)
is used to build it. Building Gossamer requires version 1.20 or higher of
[Golang](https://go.dev/dl/).

### Installation

Clone the [Gossamer](https://github.com/ChainSafe/gossamer) repository and
checkout the `development` branch:

```sh
git clone git@github.com:ChainSafe/gossamer
cd gossamer
git checkout development
```

Build Gossamer:

```sh
make gossamer
```

Or build Gossamer _and_ move the resulting executable to `$GOPATH/bin`:

```sh
make install
```

To install Gossamer

## Use Gossamer

A comprehensive guide to
[Gossamer's end-user capabilities](cmd/gossamer/README.md) is located in the
`cmd/gossamer` directory. What follows is a guide to Gossamer's capabilities as
a Polkadot Host.

### Chain Specifications

A chain specification is a JSON document that defines the
[genesis](https://wiki.polkadot.network/docs/glossary#genesis) block of a
blockchain network, as well as network parameters and metadata (e.g. network
name, bootnodes,
[telemetry endpoints](https://wiki.polkadot.network/docs/build-node-management#monitoring-and-telemetry),
etc). It is necessary to provide Gossamer with a chain specification in order to
use it as a Polkadot Host. The Gossamer repository includes a number of chain
specifications, some of which will be used in this guide.

### Configuration Files

Gossamer exposes a number of configuration parameters, such as the location of a
chain specification file. Although it's possible to use command-line parameters,
this guide will focus on the usage of Gossamer TOML configuration files, which
define a set of configuration values in a declarative, portable, reusable
format. The chain specifications that are used in this guide are each
accompanied by one or more configuration files.

### Single-Node Development Network

The name of the Polkadot test network is "Westend", and the Gossamer repository
includes a chain specification and configuration file for a single-node, local
Westend test network.

First, initialize the directory that will be used by the Gossamer node to manage
its state:

```sh
./bin/gossamer init --force --chain westend-dev
```

Now, start Gossamer as a host for the local Westend development chain:

```sh
./bin/gossamer --chain westend-dev
```

### Multi-Node Development Network

The multi-node development network includes three participants: the Alice, Bob,
and Charlie test accounts. In three separate terminals, initialize the data
directories for the three Gossamer instances:

```sh
./bin/gossamer init --force --chain westend-local --alice
```

```sh
./bin/gossamer init --force --chain westend-local --bob
```

```sh
./bin/gossamer init --force --config westend-local --charlie
```

Then start the three hosts:

```sh
./bin/gossamer --chain westend-local --alice
```

```sh
./bin/gossamer --chain westend-local --bob
```

```sh
./bin/gossamer --chain westend-local --charlie
```

## Standalone Packages

In addition to the core functionality provided by Gossamer, we have developed some standalone packages that can be used independently. These packages are located in the `pkg` directory and serve various utility purposes. Here’s an overview of some of these packages:

### Scale

To support parity's [scale type encoding](https://docs.substrate.io/reference/scale-codec/) in golang.  
More details [here](./pkg/scale/README.md)

### Trie

The `trie` package includes multiple implementations of polkadot merkle tries. These implementations are useful for various applications requiring efficient data structures. Here are the key implementations:

#### In-Memory Trie

This implementation supports polkadot merkle tries that are stored entirely in memory. It includes features for backing up the trie using a database to ensure persistence.

#### TrieDB

An evolution of the in-memory trie, `TrieDB` introduces lazy loading capabilities from the underlying database. This approach optimizes performance and resource usage by loading data only as needed.

For more details on how to use `TrieDB`, refer to the specific [README](pkg/trie/triedb/README.md)


## Contribute

- Check out the [Contributing Guidelines](.github/CONTRIBUTING.md) and our
  [style guide](.github/CODE_STYLE.md).
- Have questions or just want to say hi? Join us on
  [Discord](https://discord.gg/Xdc5xjE)!

## Donate

Our work on Gossamer is funded by the community. If you'd like to support us
with a donation:

- DOT:
  [`14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75`](https://polkadot.subscan.io/account/14gaKBxYkbBh2SKGtRDdhuhtyGAs5XLh55bE5x4cDi5CmL75)
- KSM:
  [`FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf`](https://kusama.subscan.io/account/FAjhFSFoM6X8CxeSp6JE2fPECauCA5NxyB1rAGNSkrVaMtf)
- ETH/DAI: `0x764001D60E69f0C3D0b41B0588866cFaE796972c`

## ChainSafe Security Policy

We take all security issues seriously, if you believe you have found a security
issue within a ChainSafe project please notify us immediately. If an issue is
confirmed, we will take all necessary precautions to ensure a statement and
patch release is made in a timely manner.

### Reporting a Security Bug

Please email us a description of the flaw and any related information (e.g.
reproduction steps, version) to
[security at chainsafe dot io](mailto:security@chainsafe.io).

## License

_GNU Lesser General Public License v3.0_

<br />
<p align="center">
 <img src="/docs/docs/assets/img/chainsafe_gopher.png">
</p>


gossamer

An IPFS implementation in Go. It provides content-addressable storage which can be used for decentralized storage in DApps. It is based on the IPFS protocol

<h1 align="center">
  <br>
  <a href="https://github.com/ipfs/kubo/blob/master/docs/logo/"><img src="https://user-images.githubusercontent.com/157609/250148884-d6d12db8-fdcf-4be3-8546-2550b69845d8.png" alt="Kubo logo" title="Kubo logo" width="200"></a>
  <br>
  Kubo: IPFS Implementation in Go
  <br>
</h1>

<p align="center" style="font-size: 1.2rem;">The first implementation of IPFS.</p>

<p align="center">
  <a href="https://ipfs.tech"><img src="https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square" alt="Official Part of IPFS Project"></a>
  <a href="https://discuss.ipfs.tech"><img alt="Discourse Forum" src="https://img.shields.io/discourse/posts?server=https%3A%2F%2Fdiscuss.ipfs.tech"></a>
  <a href="https://docs.ipfs.tech/community/"><img alt="Matrix" src="https://img.shields.io/matrix/ipfs-space%3Aipfs.io?server_fqdn=matrix.org"></a>
  <a href="https://github.com/ipfs/kubo/actions"><img src="https://img.shields.io/github/actions/workflow/status/ipfs/kubo/gobuild.yml?branch=master"></a>
  <a href="https://github.com/ipfs/kubo/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/ipfs/kubo?filter=!*rc*"></a>
</p>

<hr />

<p align="center">
<b><a href="#what-is-kubo">What is Kubo?</a></b> | <b><a href="#quick-taste">Quick Taste</a></b> | <b><a href="#install">Install</a></b> | <b><a href="#documentation">Documentation</a></b> | <b><a href="#development">Development</a></b> | <b><a href="#getting-help">Getting Help</a></b>
</p>

## What is Kubo?

Kubo was the first [IPFS](https://docs.ipfs.tech/concepts/what-is-ipfs/) implementation and is the [most widely used one today](https://probelab.io/ipfs/topology/#chart-agent-types-avg). It takes an opinionated approach to content-addressing ([CIDs](https://docs.ipfs.tech/concepts/glossary/#cid), [DAGs](https://docs.ipfs.tech/concepts/glossary/#dag)) that maximizes interoperability: [UnixFS](https://docs.ipfs.tech/concepts/glossary/#unixfs) for files and directories, [HTTP Gateways](https://docs.ipfs.tech/concepts/glossary/#gateway) for web browsers, [Bitswap](https://docs.ipfs.tech/concepts/glossary/#bitswap) and [HTTP](https://specs.ipfs.tech/http-gateways/trustless-gateway/) for verifiable data transfer.

**Features:**

- Runs an IPFS node as a network service (LAN [mDNS](https://github.com/libp2p/specs/blob/master/discovery/mdns.md) and WAN [Amino DHT](https://docs.ipfs.tech/concepts/glossary/#dht))
- [Command-line interface](https://docs.ipfs.tech/reference/kubo/cli/) (`ipfs --help`)
- [WebUI](https://github.com/ipfs/ipfs-webui/#readme) for node management
- [HTTP Gateway](https://specs.ipfs.tech/http-gateways/) for trusted and [trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval
- [HTTP RPC API](https://docs.ipfs.tech/reference/kubo/rpc/) to control the daemon
- [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) client and server for [delegated routing](./docs/delegated-routing.md)
- [FUSE mounts](./docs/fuse.md) for mounting `/ipfs`, `/ipns`, and `/mfs` as local filesystems (experimental)
- [Content blocking](./docs/content-blocking.md) for public node operators

**Other IPFS implementations:** [Helia](https://github.com/ipfs/helia) (JavaScript), [more...](https://docs.ipfs.tech/concepts/ipfs-implementations/)

## Quick Taste

After [installing Kubo](#install), verify it works:

```console
$ ipfs init
generating ED25519 keypair...done
peer identity: 12D3KooWGcSLQdLDBi2BvoP8WnpdHvhWPbxpGcqkf93rL2XMZK7R

$ ipfs daemon &
Daemon is ready

$ echo "hello IPFS" | ipfs add -q --cid-version 1
bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa

$ ipfs cat bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa
hello IPFS
```

Verify this CID is provided by your node to the IPFS network: <https://check.ipfs.network/?cid=bafkreicouv3sksjuzxb3rbb6rziy6duakk2aikegsmtqtz5rsuppjorxsa>

See `ipfs add --help` for all import options. Ready for more? Follow the [command-line quick start](https://docs.ipfs.tech/how-to/command-line-quick-start/).

## Install

Follow the [official installation guide](https://docs.ipfs.tech/install/command-line/), or choose: [prebuilt binary](#official-prebuilt-binaries) | [Docker](#docker) | [package manager](#package-managers) | [from source](#build-from-source).

Prefer a GUI? Try [IPFS Desktop](https://docs.ipfs.tech/install/ipfs-desktop/) and/or [IPFS Companion](https://docs.ipfs.tech/install/ipfs-companion/).

### Minimal System Requirements

Kubo runs on most Linux, macOS, and Windows systems. For optimal performance, we recommend at least 6 GB of RAM and 2 CPU cores (more is ideal, as Kubo is highly parallel).

> [!IMPORTANT]
> Larger pinsets require additional memory, with an estimated ~1 GiB of RAM per 20 million items for reproviding to the Amino DHT.

> [!CAUTION]
> Systems with less than the recommended memory may experience instability, frequent OOM errors or restarts, and missing data announcement (reprovider window), which can make data fully or partially inaccessible to other peers. Running Kubo on underprovisioned hardware is at your own risk.

### Official Prebuilt Binaries

Download from https://dist.ipfs.tech#kubo or [GitHub Releases](https://github.com/ipfs/kubo/releases/latest).

### Docker

Official images are published at https://hub.docker.com/r/ipfs/kubo/: [![Docker Image Version (latest semver)](https://img.shields.io/docker/v/ipfs/kubo?color=blue&label=kubo%20docker%20image&logo=docker&sort=semver&style=flat-square&cacheSeconds=3600)](https://hub.docker.com/r/ipfs/kubo/)

#### 🟢 Release Images

Use these for production deployments.

- `latest` and [`release`](https://hub.docker.com/r/ipfs/kubo/tags?name=release) always point at [the latest stable release](https://github.com/ipfs/kubo/releases/latest)
- [`vN.N.N`](https://hub.docker.com/r/ipfs/kubo/tags?name=v) points at a specific [release tag](https://github.com/ipfs/kubo/releases)

```console
$ docker pull ipfs/kubo:latest
$ docker run --rm -it --net=host ipfs/kubo:latest
```

To [customize your node](https://docs.ipfs.tech/install/run-ipfs-inside-docker/#customizing-your-node), pass config via `-e` or mount scripts in `/container-init.d`.

#### 🟠 Developer Preview Images

For internal testing, not intended for production.

- [`master-latest`](https://hub.docker.com/r/ipfs/kubo/tags?name=master-latest) points at `HEAD` of [`master`](https://github.com/ipfs/kubo/commits/master/)
- [`master-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=master-2) points at a specific commit

#### 🔴 Internal Staging Images

For testing arbitrary commits and experimental patches (force push to `staging` branch).

- [`staging-latest`](https://hub.docker.com/r/ipfs/kubo/tags?name=staging-latest) points at `HEAD` of [`staging`](https://github.com/ipfs/kubo/commits/staging/)
- [`staging-YYYY-DD-MM-GITSHA`](https://hub.docker.com/r/ipfs/kubo/tags?name=staging-2) points at a specific commit

### Build from Source

![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/ipfs/kubo?label=Requires%20Go&logo=go&style=flat-square&cacheSeconds=3600)

```bash
git clone https://github.com/ipfs/kubo.git
cd kubo
make build    # creates cmd/ipfs/ipfs
make install  # installs to $GOPATH/bin/ipfs
```

See the [Developer Guide](docs/developer-guide.md) for details, Windows instructions, and troubleshooting.

### Package Managers

Kubo is available in community-maintained packages across many operating systems, Linux distributions, and package managers. See [Repology](https://repology.org/project/kubo/versions) for the full list: [![Packaging status](https://repology.org/badge/tiny-repos/kubo.svg)](https://repology.org/project/kubo/versions)

> [!WARNING]
> These packages are maintained by third-party volunteers. The IPFS Project and Kubo maintainers are not responsible for their contents or supply chain security. For increased security, [build from source](#build-from-source).

#### Linux

| Distribution | Install | Version |
|--------------|---------|---------|
| Ubuntu | [PPA](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs): `sudo apt install ipfs-kubo` | [![PPA: twdragon](https://img.shields.io/badge/PPA-twdragon-E95420?logo=ubuntu)](https://launchpad.net/~twdragon/+archive/ubuntu/ipfs) |
| Arch | `pacman -S kubo` | [![Arch package](https://repology.org/badge/version-for-repo/arch/kubo.svg)](https://archlinux.org/packages/extra/x86_64/kubo/) |
| Fedora | [COPR](https://copr.fedorainfracloud.org/coprs/taw/ipfs/): `dnf install kubo` | [![COPR: taw](https://img.shields.io/badge/COPR-taw-51A2DA?logo=fedora)](https://copr.fedorainfracloud.org/coprs/taw/ipfs/) |
| Nix | `nix-env -i kubo` | [![nixpkgs unstable](https://repology.org/badge/version-for-repo/nix_unstable/kubo.svg)](https://search.nixos.org/packages?query=kubo) |
| Gentoo | `emerge -a net-p2p/kubo` | [![Gentoo package](https://repology.org/badge/version-for-repo/gentoo/kubo.svg)](https://packages.gentoo.org/packages/net-p2p/kubo) |
| openSUSE | `zypper install kubo` | [![openSUSE Tumbleweed](https://repology.org/badge/version-for-repo/opensuse_tumbleweed/kubo.svg)](https://software.opensuse.org/package/kubo) |
| Solus | `sudo eopkg install kubo` | [![Solus package](https://repology.org/badge/version-for-repo/solus/kubo.svg)](https://packages.getsol.us/shannon/k/kubo/) |
| Guix | `guix install kubo` | [![Guix package](https://repology.org/badge/version-for-repo/gnuguix/kubo.svg)](https://packages.guix.gnu.org/packages/kubo/) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |

~~Snap~~ no longer supported ([#8688](https://github.com/ipfs/kubo/issues/8688))

#### macOS

| Manager | Install | Version |
|---------|---------|---------|
| Homebrew | `brew install ipfs` | [![Homebrew](https://repology.org/badge/version-for-repo/homebrew/kubo.svg)](https://formulae.brew.sh/formula/ipfs) |
| MacPorts | `sudo port install ipfs` | [![MacPorts](https://repology.org/badge/version-for-repo/macports/kubo.svg)](https://ports.macports.org/port/ipfs/) |
| Nix | `nix-env -i kubo` | [![nixpkgs unstable](https://repology.org/badge/version-for-repo/nix_unstable/kubo.svg)](https://search.nixos.org/packages?query=kubo) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |

#### Windows

| Manager | Install | Version |
|---------|---------|---------|
| Scoop | `scoop install kubo` | [![Scoop](https://repology.org/badge/version-for-repo/scoop/kubo.svg)](https://scoop.sh/#/apps?q=kubo) |
| _other_ | [See Repology for the full list](https://repology.org/project/kubo/versions) | |

~~Chocolatey~~ no longer supported ([#9341](https://github.com/ipfs/kubo/issues/9341))

## Documentation

| Topic | Description |
|-------|-------------|
| [Configuration](docs/config.md) | All config options reference |
| [Environment variables](docs/environment-variables.md) | Runtime settings via env vars |
| [Experimental features](docs/experimental-features.md) | Opt-in features in development |
| [HTTP Gateway](docs/gateway.md) | Path, subdomain, and trustless gateway setup |
| [HTTP RPC clients](docs/http-rpc-clients.md) | Client libraries for Go, JS |
| [Delegated routing](docs/delegated-routing.md) | Multi-router and HTTP routing |
| [Metrics & monitoring](docs/metrics.md) | Prometheus metrics |
| [FUSE mounts](docs/fuse.md) | Mount `/ipfs`, `/ipns`, `/mfs` as local filesystems |
| [Content blocking](docs/content-blocking.md) | Denylist for public nodes |
| [Customizing](docs/customizing.md) | Unsure if use Plugins, Boxo, or fork? |
| [Debug guide](docs/debug-guide.md) | CPU profiles, memory analysis, tracing |
| [Changelogs](docs/changelogs/) | Release notes for each version |
| [All documentation](https://github.com/ipfs/kubo/tree/master/docs) | Full list of docs |

## Development

See the [Developer Guide](docs/developer-guide.md) for build instructions, testing, and contribution workflow. AI coding agents should follow [AGENTS.md](AGENTS.md).

## Getting Help

- [IPFS Forum](https://discuss.ipfs.tech) - community support, questions, and discussion
- [Community](https://docs.ipfs.tech/community/) - chat, events, and working groups
- [GitHub Issues](https://github.com/ipfs/kubo/issues) - bug reports for Kubo specifically
- [IPFS Docs Issues](https://github.com/ipfs/ipfs-docs/issues) - documentation issues

## Security Issues

See [`SECURITY.md`](SECURITY.md).

## Contributing

[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Developer Guide](docs/developer-guide.md).

This repository follows the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).

## Maintainer Info

<a href="https://ipshipyard.com/"><img align="right" src="https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272" /></a>

> [!NOTE]
> Kubo is maintained by the [Shipyard](https://ipshipyard.com/) team.
>
> [Release Process](https://ipshipyard.notion.site/Kubo-Release-Process-6dba4f5755c9458ab5685eeb28173778)

## License

Dual-licensed under Apache 2.0 and MIT:

- [LICENSE-APACHE](LICENSE-APACHE)
- [LICENSE-MIT](LICENSE-MIT)


kubo

A complete implementation of a Lightning Network node

## Lightning Network Daemon

[![Release build](https://github.com/lightningnetwork/lnd/actions/workflows/release.yaml/badge.svg)](https://github.com/lightningnetwork/lnd/actions/workflows/release.yaml)
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/lightningnetwork/lnd/blob/master/LICENSE)
[![Irc](https://img.shields.io/badge/chat-on%20libera-brightgreen.svg)](https://web.libera.chat/#lnd)
[![Godoc](https://godoc.org/github.com/lightningnetwork/lnd?status.svg)](https://godoc.org/github.com/lightningnetwork/lnd)
[![Go Report Card](https://goreportcard.com/badge/github.com/lightningnetwork/lnd)](https://goreportcard.com/report/github.com/lightningnetwork/lnd)

<img src="logo.png">

The Lightning Network Daemon (`lnd`) - is a complete implementation of a
[Lightning Network](https://lightning.network) node.  `lnd` has several pluggable back-end
chain services including [`btcd`](https://github.com/btcsuite/btcd) (a
full-node), [`bitcoind`](https://github.com/bitcoin/bitcoin), and
[`neutrino`](https://github.com/lightninglabs/neutrino) (a new experimental light client). The project's codebase uses the
[btcsuite](https://github.com/btcsuite/) set of Bitcoin libraries, and also
exports a large set of isolated re-usable Lightning Network related libraries
within it.  In the current state `lnd` is capable of:
* Creating channels.
* Closing channels.
* Completely managing all channel states (including the exceptional ones!).
* Maintaining a fully authenticated+validated channel graph.
* Performing path finding within the network, passively forwarding incoming payments.
* Sending outgoing [onion-encrypted payments](https://github.com/lightningnetwork/lightning-onion)
through the network.
* Updating advertised fee schedules.
* Automatic channel management ([`autopilot`](https://github.com/lightningnetwork/lnd/tree/master/autopilot)).

## Lightning Network Specification Compliance
`lnd` _fully_ conforms to the [Lightning Network specification
(BOLTs)](https://github.com/lightningnetwork/lightning-rfc). BOLT stands for:
Basis of Lightning Technology. The specifications are currently being drafted
by several groups of implementers based around the world including the
developers of `lnd`. The set of specification documents as well as our
implementation of the specification are still a work-in-progress. With that
said, the current status of `lnd`'s BOLT compliance is:

  - [X] BOLT 1: Base Protocol
  - [X] BOLT 2: Peer Protocol for Channel Management
  - [X] BOLT 3: Bitcoin Transaction and Script Formats
  - [X] BOLT 4: Onion Routing Protocol
  - [X] BOLT 5: Recommendations for On-chain Transaction Handling
  - [X] BOLT 7: P2P Node and Channel Discovery
  - [X] BOLT 8: Encrypted and Authenticated Transport
  - [X] BOLT 9: Assigned Feature Flags
  - [X] BOLT 10: DNS Bootstrap and Assisted Node Location
  - [X] BOLT 11: Invoice Protocol for Lightning Payments

## Developer Resources

The daemon has been designed to be as developer friendly as possible in order
to facilitate application development on top of `lnd`. Two primary RPC
interfaces are exported: an HTTP REST API, and a [gRPC](https://grpc.io/)
service. The exported APIs are not yet stable, so be warned: they may change
drastically in the near future.

An automatically generated set of documentation for the RPC APIs can be found
at [api.lightning.community](https://api.lightning.community). A set of developer
resources including guides, articles, example applications and community resources can be found at:
[docs.lightning.engineering](https://docs.lightning.engineering).

Finally, we also have an active
[Slack](https://lightning.engineering/slack.html) where protocol developers, application developers, testers and users gather to
discuss various aspects of `lnd` and also Lightning in general.

First-time contributors are [highly encouraged to start with code review
first](docs/review.md), before creating their own Pull Requests.

## Installation
  In order to build from source, please see [the installation
  instructions](docs/INSTALL.md).

## Docker
  To run lnd from Docker, please see the main [Docker instructions](docs/DOCKER.md)

## IRC
  * irc.libera.chat
  * channel #lnd
  * [webchat](https://web.libera.chat/#lnd)

## Safety

When operating a mainnet `lnd` node, please refer to our [operational safety
guidelines](docs/safety.md). It is important to note that `lnd` is still
**beta** software and that ignoring these operational guidelines can lead to
loss of funds.

## Security

The developers of `lnd` take security _very_ seriously. The disclosure of
security vulnerabilities helps us secure the health of `lnd`, privacy of our
users, and also the health of the Lightning Network as a whole.  If you find
any issues regarding security or privacy, please disclose the information
responsibly by sending an email to security at lightning dot engineering,
preferably encrypted using our designated PGP key
(`91FE464CD75101DA6B6BAB60555C6465E5BCB3AF`) which can be found
[here](https://gist.githubusercontent.com/Roasbeef/6fb5b52886183239e4aa558f83d085d3/raw/1ecb328bbcf36f76ead67f08008f8db1da07e60e/security@lightning.engineering).

## Further reading
* [Step-by-step send payment guide with docker](https://github.com/lightningnetwork/lnd/tree/master/docker)
* [Contribution guide](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md)


Go library to interface with Solana JSON RPC and WebSocket interfaces

solana-go

A Go-based framework for building Polkadot/Substrate-compatible runtimes

# Gosemble

[![Go Report Card](https://goreportcard.com/badge/github.com/LimeChain/gosemble)](https://goreportcard.com/report/github.com/LimeChain/gosemble)
[![codecov](https://codecov.io/github/LimeChain/gosemble/graph/badge.svg?token=48SIN10OBK)](https://codecov.io/github/LimeChain/gosemble)

> [!WARNING]
> Gosemble is in pre-production and the code is not yet audited. Use at your own risk.

Go implementation of Polkadot/Substrate compatible runtimes. For more details, check
the [Official Documentation](https://limechain.github.io/gosemble/)

### Quick Start

#### Prerequisites

- [Git](https://git-scm.com/downloads)
- [Go 1.21](https://golang.org/doc/install)
- [Docker](https://docs.docker.com/install/)
- [Rust](https://docs.substrate.io/install/) (for building the Substrate node)

#### Clone the repository

```bash
git clone https://github.com/LimeChain/gosemble.git
cd gosemble
```

#### Pull all necessary git submodules

```bash
git submodule update --init --recursive
```

#### Build

To build a runtime, execute: 

```bash
make build-docker-release
```

#### Start a local network

After the runtime is built, start a local network using Substrate host:

```bash
make start-network
```

#### Run Tests

After the Runtime is built, execute the tests with the help of [Gossamer](https://github.com/LimeChain/gossamer), which
is used to import necessary Polkadot Host functionality and interact with the Runtime.

```bash
make test-unit
make test-integration
```


gosemble

Official Go implementation of the Ethereum protocol

## Go Ethereum

Golang execution layer implementation of the Ethereum protocol.

[![API Reference](
https://pkg.go.dev/badge/github.com/ethereum/go-ethereum
)](https://pkg.go.dev/github.com/ethereum/go-ethereum?tab=doc)
[![Go Report Card](https://goreportcard.com/badge/github.com/ethereum/go-ethereum)](https://goreportcard.com/report/github.com/ethereum/go-ethereum)
[![Travis](https://app.travis-ci.com/ethereum/go-ethereum.svg?branch=master)](https://app.travis-ci.com/github/ethereum/go-ethereum)
[![Discord](https://img.shields.io/badge/discord-join%20chat-blue.svg)](https://discord.gg/nthXNEv)
[![Twitter](https://img.shields.io/twitter/follow/go_ethereum)](https://x.com/go_ethereum)

Automated builds are available for stable releases and the unstable master branch. Binary
archives are published at https://geth.ethereum.org/downloads/.

## Building the source

For prerequisites and detailed build instructions please read the [Installation Instructions](https://geth.ethereum.org/docs/getting-started/installing-geth).

Building `geth` requires both a Go (version 1.23 or later) and a C compiler. You can install
them using your favourite package manager. Once the dependencies are installed, run

```shell
make geth
```

or, to build the full suite of utilities:

```shell
make all
```

## Executables

The go-ethereum project comes with several wrappers/executables found in the `cmd`
directory.

|  Command   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :--------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`geth`** | Our main Ethereum CLI client. It is the entry point into the Ethereum network (main-, test- or private net), capable of running as a full node (default), archive node (retaining all historical state) or a light node (retrieving data live). It can be used by other processes as a gateway into the Ethereum network via JSON RPC endpoints exposed on top of HTTP, WebSocket and/or IPC transports. `geth --help` and the [CLI page](https://geth.ethereum.org/docs/fundamentals/command-line-options) for command line options. |
|   `clef`   | Stand-alone signing tool, which can be used as a backend signer for `geth`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|  `devp2p`  | Utilities to interact with nodes on the networking layer, without running a full blockchain.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|  `abigen`  | Source code generator to convert Ethereum contract definitions into easy-to-use, compile-time type-safe Go packages. It operates on plain [Ethereum contract ABIs](https://docs.soliditylang.org/en/develop/abi-spec.html) with expanded functionality if the contract bytecode is also available. However, it also accepts Solidity source files, making development much more streamlined. Please see our [Native DApps](https://geth.ethereum.org/docs/developers/dapp-developer/native-bindings) page for details.                                  |
|   `evm`    | Developer utility version of the EVM (Ethereum Virtual Machine) that is capable of running bytecode snippets within a configurable environment and execution mode. Its purpose is to allow isolated, fine-grained debugging of EVM opcodes (e.g. `evm --code 60ff60ff --debug run`).                                                                                                                                                                                                                                               |
| `rlpdump`  | Developer utility tool to convert binary RLP ([Recursive Length Prefix](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp)) dumps (data encoding used by the Ethereum protocol both network as well as consensus wise) to user-friendlier hierarchical representation (e.g. `rlpdump --hex CE0183FFFFFFC4C304050583616263`).                                                                                                                                                                                |

## Running `geth`

Going through all the possible command line flags is out of scope here (please consult our
[CLI Wiki page](https://geth.ethereum.org/docs/fundamentals/command-line-options)),
but we've enumerated a few common parameter combos to get you up to speed quickly
on how you can run your own `geth` instance.

### Hardware Requirements

Minimum:

* CPU with 4+ cores
* 8GB RAM
* 1TB free storage space to sync the Mainnet
* 8 MBit/sec download Internet service

Recommended:

* Fast CPU with 8+ cores
* 16GB+ RAM
* High-performance SSD with at least 1TB of free space
* 25+ MBit/sec download Internet service

### Full node on the main Ethereum network

By far the most common scenario is people wanting to simply interact with the Ethereum
network: create accounts; transfer funds; deploy and interact with contracts. For this
particular use case, the user doesn't care about years-old historical data, so we can
sync quickly to the current state of the network. To do so:

```shell
$ geth console
```

This command will:
 * Start `geth` in snap sync mode (default, can be changed with the `--syncmode` flag),
   causing it to download more data in exchange for avoiding processing the entire history
   of the Ethereum network, which is very CPU intensive.
 * Start the built-in interactive [JavaScript console](https://geth.ethereum.org/docs/interacting-with-geth/javascript-console),
   (via the trailing `console` subcommand) through which you can interact using [`web3` methods](https://github.com/ChainSafe/web3.js/blob/0.20.7/DOCUMENTATION.md) 
   (note: the `web3` version bundled within `geth` is very old, and not up to date with official docs),
   as well as `geth`'s own [management APIs](https://geth.ethereum.org/docs/interacting-with-geth/rpc).
   This tool is optional and if you leave it out you can always attach it to an already running
   `geth` instance with `geth attach`.

### A Full node on the Holesky test network

Transitioning towards developers, if you'd like to play around with creating Ethereum
contracts, you almost certainly would like to do that without any real money involved until
you get the hang of the entire system. In other words, instead of attaching to the main
network, you want to join the **test** network with your node, which is fully equivalent to
the main network, but with play-Ether only.

```shell
$ geth --holesky console
```

The `console` subcommand has the same meaning as above and is equally
useful on the testnet too.

Specifying the `--holesky` flag, however, will reconfigure your `geth` instance a bit:

 * Instead of connecting to the main Ethereum network, the client will connect to the Holesky 
   test network, which uses different P2P bootnodes, different network IDs and genesis
   states.
 * Instead of using the default data directory (`~/.ethereum` on Linux for example), `geth`
   will nest itself one level deeper into a `holesky` subfolder (`~/.ethereum/holesky` on
   Linux). Note, on OSX and Linux this also means that attaching to a running testnet node
   requires the use of a custom endpoint since `geth attach` will try to attach to a
   production node endpoint by default, e.g.,
   `geth attach <datadir>/holesky/geth.ipc`. Windows users are not affected by
   this.

*Note: Although some internal protective measures prevent transactions from
crossing over between the main network and test network, you should always
use separate accounts for play and real money. Unless you manually move
accounts, `geth` will by default correctly separate the two networks and will not make any
accounts available between them.*

### Configuration

As an alternative to passing the numerous flags to the `geth` binary, you can also pass a
configuration file via:

```shell
$ geth --config /path/to/your_config.toml
```

To get an idea of how the file should look like you can use the `dumpconfig` subcommand to
export your existing configuration:

```shell
$ geth --your-favourite-flags dumpconfig
```

#### Docker quick start

One of the quickest ways to get Ethereum up and running on your machine is by using
Docker:

```shell
docker run -d --name ethereum-node -v /Users/alice/ethereum:/root \
           -p 8545:8545 -p 30303:30303 \
           ethereum/client-go
```

This will start `geth` in snap-sync mode with a DB memory allowance of 1GB, as the
above command does.  It will also create a persistent volume in your home directory for
saving your blockchain as well as map the default ports. There is also an `alpine` tag
available for a slim version of the image.

Do not forget `--http.addr 0.0.0.0`, if you want to access RPC from other containers
and/or hosts. By default, `geth` binds to the local interface and RPC endpoints are not
accessible from the outside.

### Programmatically interfacing `geth` nodes

As a developer, sooner rather than later you'll want to start interacting with `geth` and the
Ethereum network via your own programs and not manually through the console. To aid
this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://ethereum.org/en/developers/docs/apis/json-rpc/)
and [`geth` specific APIs](https://geth.ethereum.org/docs/interacting-with-geth/rpc)).
These can be exposed via HTTP, WebSockets and IPC (UNIX sockets on UNIX based
platforms, and named pipes on Windows).

The IPC interface is enabled by default and exposes all the APIs supported by `geth`,
whereas the HTTP and WS interfaces need to manually be enabled and only expose a
subset of APIs due to security reasons. These can be turned on/off and configured as
you'd expect.

HTTP based JSON-RPC API options:

  * `--http` Enable the HTTP-RPC server
  * `--http.addr` HTTP-RPC server listening interface (default: `localhost`)
  * `--http.port` HTTP-RPC server listening port (default: `8545`)
  * `--http.api` API's offered over the HTTP-RPC interface (default: `eth,net,web3`)
  * `--http.corsdomain` Comma separated list of domains from which to accept cross-origin requests (browser enforced)
  * `--ws` Enable the WS-RPC server
  * `--ws.addr` WS-RPC server listening interface (default: `localhost`)
  * `--ws.port` WS-RPC server listening port (default: `8546`)
  * `--ws.api` API's offered over the WS-RPC interface (default: `eth,net,web3`)
  * `--ws.origins` Origins from which to accept WebSocket requests
  * `--ipcdisable` Disable the IPC-RPC server
  * `--ipcpath` Filename for IPC socket/pipe within the datadir (explicit paths escape it)

You'll need to use your own programming environments' capabilities (libraries, tools, etc) to
connect via HTTP, WS or IPC to a `geth` node configured with the above flags and you'll
need to speak [JSON-RPC](https://www.jsonrpc.org/specification) on all transports. You
can reuse the same connection for multiple requests!

**Note: Please understand the security implications of opening up an HTTP/WS based
transport before doing so! Hackers on the internet are actively trying to subvert
Ethereum nodes with exposed APIs! Further, all browser tabs can access locally
running web servers, so malicious web pages could try to subvert locally available
APIs!**

### Operating a private network

Maintaining your own private network is more involved as a lot of configurations taken for
granted in the official networks need to be manually set up.

Unfortunately since [the Merge](https://ethereum.org/en/roadmap/merge/) it is no longer possible
to easily set up a network of geth nodes without also setting up a corresponding beacon chain.

There are three different solutions depending on your use case:

  * If you are looking for a simple way to test smart contracts from go in your CI, you can use the [Simulated Backend](https://geth.ethereum.org/docs/developers/dapp-developer/native-bindings#blockchain-simulator).
  * If you want a convenient single node environment for testing, you can use our [Dev Mode](https://geth.ethereum.org/docs/developers/dapp-developer/dev-mode).
  * If you are looking for a multiple node test network, you can set one up quite easily with [Kurtosis](https://geth.ethereum.org/docs/fundamentals/kurtosis).

## Contribution

Thank you for considering helping out with the source code! We welcome contributions
from anyone on the internet, and are grateful for even the smallest of fixes!

If you'd like to contribute to go-ethereum, please fork, fix, commit and send a pull request
for the maintainers to review and merge into the main code base. If you wish to submit
more complex changes though, please check up with the core devs first on [our Discord Server](https://discord.gg/invite/nthXNEv)
to ensure those changes are in line with the general philosophy of the project and/or get
some early feedback which can make both your efforts much lighter as well as our review
and merge procedures quick and simple.

Please make sure your contributions adhere to our coding guidelines:

 * Code must adhere to the official Go [formatting](https://golang.org/doc/effective_go.html#formatting)
   guidelines (i.e. uses [gofmt](https://golang.org/cmd/gofmt/)).
 * Code must be documented adhering to the official Go [commentary](https://golang.org/doc/effective_go.html#commentary)
   guidelines.
 * Pull requests need to be based on and opened against the `master` branch.
 * Commit messages should be prefixed with the package(s) they modify.
   * E.g. "eth, rpc: make trace configs optional"

Please see the [Developers' Guide](https://geth.ethereum.org/docs/developers/geth-developer/dev-guide)
for more details on configuring your environment, managing project dependencies, and
testing procedures.

### Contributing to geth.ethereum.org

For contributions to the [go-ethereum website](https://geth.ethereum.org), please checkout and raise pull requests against the `website` branch.
For more detailed instructions please see the `website` branch [README](https://github.com/ethereum/go-ethereum/tree/website#readme) or the 
[contributing](https://geth.ethereum.org/docs/developers/geth-developer/contributing) page of the website.

## License

The go-ethereum library (i.e. all code outside of the `cmd` directory) is licensed under the
[GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html),
also included in our repository in the `COPYING.LESSER` file.

The go-ethereum binaries (i.e. all code inside of the `cmd` directory) are licensed under the
[GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), also
included in our repository in the `COPYING` file.


go-ethereum

Local monitoring tool for a Cardano Node. It's a TUI (terminal user interface) designed to fit most screens

# nview

[![CI](https://github.com/blinklabs-io/nview/actions/workflows/go-test.yml/badge.svg)](https://github.com/blinklabs-io/nview/actions/workflows/go-test.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/blinklabs-io/nview)](https://goreportcard.com/report/github.com/blinklabs-io/nview)
[![Go Version](https://img.shields.io/badge/go-1.25+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/blinklabs-io/nview/blob/main/LICENSE)

nview is a local monitoring tool for Cardano nodes, supporting multiple
implementations including cardano-node, Dingo, and Amaru. It's designed to
complement remote monitoring tools by providing a local command-line view of
running nodes. The TUI (terminal user interface) is built to fit most screens
and provides real-time metrics and status information.

<div align="center">
    <img src="./nview-20240208.png" alt="nview screenshot" width="640">
</div>

## Design and functionality

The goal with nview is to provide an alternative to the Guild LiveView
(gLiveView.sh) shell scripts which is shipped as a single binary with all of
the functionality included natively. This allows the tool to be more portable
to non-Linux systems by using Go standard library functionality.

The design is more in line with a 12-factor application, with no config
files or other on-disk requirements. Functionality is controlled via
environment variables within the application's context. This prevents the
application from being a drop-in replacement for gLiveView for Cardano Node
administrators, but unlocks the ability to add functionality beyond that
easily attainable with a shell script.

### Multi-Implementation Support

nview automatically detects and supports multiple Cardano node implementations:

- **cardano-node**: The official Cardano node implementation
- **Dingo**: A Cardano node implementation focused on performance
- **Amaru**: Another Cardano node implementation with specific optimizations

The tool automatically detects the running node type based on Prometheus metrics
and adjusts its display accordingly. No configuration changes are needed - just
run nview against any supported Cardano node.

## Usage

Running nview against a running Cardano Node will work out of the box with a
default Cardano Node configuration, which exposes metrics in Prometheus data
format on a specific port. nview automatically detects the node implementation
(cardano-node, Dingo, or Amaru) and adjusts its display accordingly.

```bash
./nview
```

Or, from source:
```bash
go run .
```

### Configuration

Configuration can be controlled by either a configuration file or environment
variables. In cases where both are present, the environment variable takes
precedence.

#### Configuration (env)

The following environment variables control the behavior of the application.

- `NODE_NAME` - Changes the name displayed by nview, default is "Cardano
  Node", maximum 19 characters
- `NETWORK` - Short-cut environment variable to use a default configuration
  for the given known named network. Overrides `CARDANO_NETWORK`, default ""
- `CARDANO_NETWORK` - Named network configured on the Cardano Node, default
  is "mainnet"
- `CARDANO_NODE_BINARY` - Specifies the node binary type
  (`cardano-node`, `dingo`, or `amaru`). If not set, nview will attempt to
  auto-detect based on metrics
- `PROM_HOST` - Sets the host address used to fetch Prometheus metrics from a
  Cardano Node, default is "127.0.0.1"
- `PROM_PORT` - Sets the host port used to fetch Prometheus metrics from a
  Cardano Node, default is 12798
- `PROM_TIMEOUT` - Sets the maximum number of seconds to wait for response
  when polling a Cardano Node for Prometheus metrics, default is 3

#### Configuration (YAML)

To use a configuration file, run `nview` with a command line flag to set the
file to load as a configuration.

```bash
./nview -config /path/to/config.yml
```

config.yaml:
```
app:
  nodeName: Cardano Node
  network:
node:
  binary: cardano-node  # or 'dingo' or 'amaru'
  network: mainnet
  port: 3001
prometheus:
  host: 127.0.0.1
  port: 12798
  timeout: 3
```

An example configuration is provided at `config.yaml.example`.

## Examples

### Running with Dingo Node

```bash
# Auto-detection (recommended)
./nview

# Or explicitly set
CARDANO_NODE_BINARY=dingo ./nview
```

### Running with Amaru Node

```bash
# Auto-detection (recommended)
./nview

# Or explicitly set
CARDANO_NODE_BINARY=amaru ./nview
```

### Custom Prometheus Port

```bash
PROM_PORT=9090 ./nview
```

### Remote Node Monitoring

```bash
PROM_HOST=192.168.1.100 PROM_PORT=12798 ./nview
```

## Troubleshooting

### Node Not Detected

If nview shows "Cardano Node" instead of the expected implementation:

1. Ensure your node is running and exposing Prometheus metrics
2. Check that the correct `PROM_HOST` and `PROM_PORT` are set
3. For manual override, set `CARDANO_NODE_BINARY` environment variable

### Connection Issues

- Verify Prometheus metrics are accessible: `curl http://127.0.0.1:12798/metrics`
- Check firewall settings if monitoring remotely
- Increase timeout if on slow networks: `PROM_TIMEOUT=10 ./nview`

### Display Issues

- Ensure terminal supports Unicode characters
- Check terminal width (minimum 112 columns recommended)
- For color issues, ensure terminal supports 256 colors

## GeoLocation

We embed free GeoLite2 city data created by MaxMind, available
from https://www.maxmind.com and licensed under CC BY-SA 4.0
<https://creativecommons.org/licenses/by-sa/4.0/>


nview

A comprehensive, production-ready Go SDK for interacting with the TRON blockchain with TRC20 token support

# 🔗 TronLib - Go SDK for TRON Blockchain

[![Go Reference](https://pkg.go.dev/badge/github.com/kslamph/tronlib.svg)](https://pkg.go.dev/github.com/kslamph/tronlib)
[![Go Report Card](https://goreportcard.com/badge/github.com/kslamph/tronlib)](https://goreportcard.com/report/github.com/kslamph/tronlib)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://codecov.io/gh/kslamph/tronlib/graph/badge.svg?token=QIN77Y7S2T)](https://codecov.io/gh/kslamph/tronlib)

A comprehensive, production-ready Go SDK for interacting with the TRON blockchain. TronLib provides high-level abstractions for common operations while maintaining flexibility for advanced use cases.

## ✨ Features

- 🚀 **Simple & Intuitive** - High-level APIs that make blockchain interaction straightforward
- 🔐 **Secure** - Built-in support for private keys and HD wallets
- 💰 **TRC20 Ready** - First-class support for TRC20 tokens with decimal conversion
- 📦 **Smart Contracts** - Deploy and interact with smart contracts effortlessly
- 🎯 **Event Decoding** - Decode transaction logs with built-in TRC20 event support
- ⚡ **Performance** - Connection pooling and efficient gRPC communication
- 🔍 **Simulation** - Test transactions before broadcasting to the network
- 📊 **Resource Management** - Handle bandwidth and energy efficiently

## 🏁 Quick Start

### Installation

```bash
go get github.com/kslamph/tronlib
```

### Simple TRX Transfer

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/kslamph/tronlib/pkg/client"
    "github.com/kslamph/tronlib/pkg/signer"
    "github.com/kslamph/tronlib/pkg/types"
)

func main() {
    // Connect to TRON node
    cli, err := client.NewClient("grpc://grpc.nile.trongrid.io:50051")
    if err != nil {
        log.Fatal(err)
    }
    defer cli.Close()

    // Create signer from private key
    signer, err := signer.NewPrivateKeySigner("your-private-key-hex")
    if err != nil {
        log.Fatal(err)
    }

    // Define addresses
    from := signer.Address()
    to, _ := types.NewAddress("TBkfmcE7pM8cwxEhATtkMFwAf1FeQcwY9x")

    // Transfer 1 TRX (1,000,000 SUN)
    tx, err := cli.Account().TransferTRX(context.Background(), from, to, 1_000_000)
    if err != nil {
        log.Fatal(err)
    }

    // Sign and broadcast
    result, err := cli.SignAndBroadcast(context.Background(), tx, client.DefaultBroadcastOptions(), signer)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Transaction ID: %s\n", result.TxID)
    fmt.Printf("Success: %v\n", result.Success)
}
```

### TRC20 Token Transfer

```go
package main

import (
    "context"
    "log"

    "github.com/shopspring/decimal"
    "github.com/kslamph/tronlib/pkg/client"
    "github.com/kslamph/tronlib/pkg/signer"
    "github.com/kslamph/tronlib/pkg/trc20"
    "github.com/kslamph/tronlib/pkg/types"
)

func main() {
    cli, _ := client.NewClient("grpc://grpc.nile.trongrid.io:50051")
    defer cli.Close()

    signer, _ := signer.NewPrivateKeySigner("your-private-key-hex")
    
    // USDT contract address on mainnet
    token, _ := types.NewAddress("TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t")
    to, _ := types.NewAddress("TBkfmcE7pM8cwxEhATtkMFwAf1FeQcwY9x")

    // Create TRC20 manager
    trc20Mgr := cli.TRC20(token)
    if trc20Mgr == nil {
        log.Fatal("Failed to create TRC20 manager")
    }

    // Transfer 10 USDT
    amount := decimal.NewFromInt(10)
    _, tx, err := trc20Mgr.Transfer(context.Background(), signer.Address(), to, amount)
    if err != nil {
        log.Fatal(err)
    }

    // Sign and broadcast
    result, err := cli.SignAndBroadcast(context.Background(), tx, client.DefaultBroadcastOptions(), signer)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("TRC20 transfer completed: %s", result.TxID)
}
```

## 📚 Documentation

To get the most out of TronLib, follow this learning path:

### 🚀 Getting Started
- **[Quick Start Guide](docs/quickstart.md)** - Step-by-step guide to basic operations

### 🏗️ Core Concepts
- **[Architecture Overview](docs/architecture.md)** - Understanding the library structure and design patterns

### 📦 Package References
Detailed documentation for each package:
- **[Types](docs/types.md)** - Address handling and fundamental types
- **[TRC20](docs/trc20.md)** - TRC20 token operations and decimal handling
- **[Smart Contracts](docs/smartcontract.md)** - Contract deployment and interaction
- **[Event Decoder](docs/eventdecoder.md)** - Transaction log decoding
- **[Utils](docs/utils.md)** - ABI encoding/decoding utilities

### 💡 Advanced Topics
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[Complete Examples](example/)** - Real-world usage examples
- **[Integration Tests](integration_test/)** - Comprehensive test suite

## 🏗️ Project Structure

```
tronlib/
├── 📁 pkg/                    # Core library packages
│   ├── 📁 client/            # gRPC client and connection management
│   ├── 📁 types/             # Fundamental types (Address, constants)
│   ├── 📁 signer/            # Private key and HD wallet management
│   ├── 📁 account/           # Account operations (balance, TRX transfers)
│   ├── 📁 trc20/             # TRC20 token operations
│   ├── 📁 smartcontract/     # Smart contract deployment and interaction
│   ├── 📁 eventdecoder/      # Event log decoding
│   ├── 📁 utils/             # ABI encoding/decoding utilities
│   ├── 📁 resources/         # Resource management (bandwidth, energy)
│   ├── 📁 voting/            # Voting operations
│   └── 📁 network/           # Network operations
├── 📁 example/               # Usage examples
├── 📁 cmd/                   # Command-line tools
├── 📁 integration_test/      # Integration tests
└── 📁 docs/                  # Documentation
```

## 🚀 Advanced Usage

### Signing Operations

TronLib provides flexible options for signing transactions and messages.

#### Manual Transaction Signing and Broadcasting

If you prefer to sign transactions manually before broadcasting, or need to integrate with external signers (e.g., hardware wallets, cloud KMS), you can use the `signer.SignTx` function.

```go
// Example for manual signing and broadcasting:
// 1. Create the transaction
// tx, err := cli.Account().TransferTRX(...)
// if err != nil {
//     log.Fatal(err)
// }
//
// 2. Sign the transaction using SignTx
// err = signer.SignTx(yourSigner, tx) // 'yourSigner' is an instance of signer.Signer
// if err != nil {
//     log.Fatal(err)
// }
//
// 3. Broadcast the signed transaction
// result, err := cli.Broadcast(context.Background(), tx)
// if err != nil {
//     log.Fatal(err)
// }
// fmt.Printf("Transaction ID: %s\n", result.TxID)
```

#### Message Signing (TIP-191 v2)

To sign arbitrary messages following the TRON Improvement Proposal 191 (TIP-191) v2 format, use the standalone `signer.SignMessageV2` function.

```go
// Sign an arbitrary message using the standalone SignMessageV2 function
// privateKey := "your-private-key-hex"
// pkSigner, err := signer.NewPrivateKeySigner(privateKey)
// if err != nil {
//     log.Fatal(err)
// }
//
// message := "Hello TronLib!"
// signature, err := signer.SignMessageV2(pkSigner, message)
// if err != nil {
//     log.Fatal(err)
// }
// fmt.Printf("Signed Message: %s\n", signature)
```

### Transaction Simulation

Test transactions before broadcasting:

```go
// Simulate before sending
simResult, err := cli.Simulate(context.Background(), tx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Energy needed: %d\n", simResult.EnergyUsage)
fmt.Printf("Would succeed: %v\n", simResult.Success)

// Only broadcast if simulation succeeds
if simResult.Success {
    result, err := cli.SignAndBroadcast(context.Background(), tx, opts, signer)
    // ...
}
```

### Smart Contract Interaction

```go
// Create contract instance
contract, err := smartcontract.NewInstance(cli, contractAddr, abiJSON)
if err != nil {
    log.Fatal(err)
}

// Call contract method
tx, err := contract.Invoke(ctx, signer.Address(), 0, "setValue", uint64(42))
if err != nil {
    log.Fatal(err)
}

// Sign and broadcast
result, err := cli.SignAndBroadcast(ctx, tx, opts, signer)
```

### Event Decoding

```go
// Decode transaction logs
for _, log := range result.Logs {
    event, err := eventdecoder.DecodeLog(log.GetTopics(), log.GetData())
    if err != nil {
        continue
    }
    
    fmt.Printf("Event: %s\n", event.EventName)
    for _, param := range event.Parameters {
        fmt.Printf("  %s: %v\n", param.Name, param.Value)
    }
}
```

## 🔧 Configuration

### Client Options

```go
cli, err := client.NewClient("grpc://grpc.trongrid.io:50051",
    client.WithTimeout(30*time.Second),     // Default timeout
    client.WithPool(5, 10),                 // Connection pool: 5 initial, 10 max
)
```

### Broadcast Options

```go
opts := client.DefaultBroadcastOptions()
opts.FeeLimit = 100_000_000                // Set fee limit in SUN
opts.WaitForReceipt = true                 // Wait for transaction receipt
opts.WaitTimeout = 20 * time.Second       // Timeout for receipt
opts.PollInterval = 500 * time.Millisecond // Polling interval
```

## 🌐 Network Support

- **Mainnet**: `grpc://grpc.trongrid.io:50051`
- **Nile Testnet**: `grpc://grpc.nile.trongrid.io:50051`
- **Local Node**: `grpc://127.0.0.1:50051`

> 💡 **Tip**: Use testnet for development and testing. Get test TRX from the [Nile Testnet Faucet](https://nile.tronscan.org/#/tools/system).

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on the foundation of TRON's gRPC API
- Uses Google Protocol Buffers for efficient communication

---

**Made with ❤️ for the TRON community**

For questions, issues, or feature requests, please open an issue on GitHub.


tronlib

High-performance middleware for transforming a state machine written in any programming language into a Byzantine Fault Tolerant replicated state machine using the Tendermint consensus and blockchain protocols

# Tendermint

_UPDATE: TendermintCore featureset is frozen for LTS, see issue https://github.com/tendermint/tendermint/issues/9972_<br/>
_This is the latest stable release used by cosmoshub-4, version 0.34.24_<br/>
_The previous main branch (v0.38.xx) can now be found under "main_backup"_<br/>

![banner](docs/tendermint-core-image.jpg)

[Byzantine-Fault Tolerant][bft] [State Machine Replication][smr]. Or
[Blockchain], for short.

[![Version][version-badge]][version-url]
[![API Reference][api-badge]][api-url]
[![Go version][go-badge]][go-url]
[![Discord chat][discord-badge]][discord-url]
[![License][license-badge]][license-url]
[![Sourcegraph][sg-badge]][sg-url]

| Branch | Tests                              | Linting                         |
|--------|------------------------------------|---------------------------------|
| main   | [![Tests][tests-badge]][tests-url] | [![Lint][lint-badge]][lint-url] |

Tendermint Core is a Byzantine Fault Tolerant (BFT) middleware that takes a
state transition machine - written in any programming language - and securely
replicates it on many machines.

For protocol details, refer to the [Tendermint Specification](./spec/README.md).

For detailed analysis of the consensus protocol, including safety and liveness
proofs, read our paper, "[The latest gossip on BFT
consensus](https://arxiv.org/abs/1807.04938)".

## Documentation

Complete documentation can be found on the
[website](https://docs.tendermint.com/).

## Releases

Please do not depend on `main` as your production branch. Use
[releases](https://github.com/tendermint/tendermint/releases) instead.

Tendermint has been in the production of private and public environments, most
notably the blockchains of the Cosmos Network. we haven't released v1.0 yet
since we are making breaking changes to the protocol and the APIs. See below for
more details about [versioning](#versioning).

In any case, if you intend to run Tendermint in production, we're happy to help.
You can contact us [over email](mailto:hello@newtendermint.org) or [join the
chat](https://discord.gg/gnoland).

More on how releases are conducted can be found [here](./RELEASES.md).

## Security

To report a security vulnerability, please [email us](mailto:security@newtendermint.org).
For examples of the kinds of bugs we're looking for, see [our security policy](SECURITY.md).

## Minimum requirements

| Requirement | Notes             |
|-------------|-------------------|
| Go version  | Go 1.18 or higher |

### Install

See the [install instructions](./docs/introduction/install.md).

### Quick Start

- [Single node](./docs/introduction/quick-start.md)
- [Local cluster using docker-compose](./docs/tools/docker-compose.md)
- [Remote cluster using Terraform and Ansible](./docs/tools/terraform-and-ansible.md)

## Contributing

Please abide by the [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.

Before contributing to the project, please take a look at the [contributing
guidelines](CONTRIBUTING.md) and the [style guide](STYLE_GUIDE.md). You may also
find it helpful to read the [specifications](./spec/README.md), and familiarize
yourself with our [Architectural Decision Records
(ADRs)](./docs/architecture/README.md) and
[Request For Comments (RFCs)](./docs/rfc/README.md).

## Versioning

### Semantic Versioning

Tendermint uses [Semantic Versioning](http://semver.org/) to determine when and
how the version changes. According to SemVer, anything in the public API can
change at any time before version 1.0.0

To provide some stability to users of 0.X.X versions of Tendermint, the MINOR
version is used to signal breaking changes across Tendermint's API. This API
includes all publicly exposed types, functions, and methods in non-internal Go
packages as well as the types and methods accessible via the Tendermint RPC
interface.

Breaking changes to these public APIs will be documented in the CHANGELOG.

### Upgrades

In an effort to avoid accumulating technical debt prior to 1.0.0, we do not
guarantee that breaking changes (ie. bumps in the MINOR version) will work with
existing Tendermint blockchains. In these cases you will have to start a new
blockchain, or write something custom to get the old data into the new chain.
However, any bump in the PATCH version should be compatible with existing
blockchain histories.

For more information on upgrading, see [UPGRADING.md](./UPGRADING.md).

### Supported Versions

Because we are a small core team, we only ship patch updates, including security
updates, to the most recent minor release and the second-most recent minor
release. Consequently, we strongly recommend keeping Tendermint up-to-date.
Upgrading instructions can be found in [UPGRADING.md](./UPGRADING.md).

## Resources

### Libraries

- [Cosmos SDK](http://github.com/cosmos/cosmos-sdk); A framework for building
  applications in Golang
- [Tendermint in Rust](https://github.com/informalsystems/tendermint-rs)
- [ABCI Tower](https://github.com/penumbra-zone/tower-abci)

### Applications

- [Cosmos Hub](https://hub.cosmos.network/)
- [Terra](https://www.terra.money/)
- [Celestia](https://celestia.org/)
- [Anoma](https://anoma.network/)
- [Vocdoni](https://docs.vocdoni.io/)

### Research

- [The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938)
- [Master's Thesis on Tendermint](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769)
- [Original Whitepaper: "Tendermint: Consensus Without Mining"](https://tendermint.com/static/docs/tendermint.pdf)
- [Tendermint Core Blog](https://medium.com/tendermint/tagged/tendermint-core)
- [Cosmos Blog](https://blog.cosmos.network/tendermint/home)

## Join us!

The development of Tendermint Core was led primarily by All in Bits, Inc. The
Tendermint trademark is owned by New Tendermint, LLC.  If you'd like to work
full-time on Tendermint2 or [gno.land](https://gno.land), [we're
hiring](mailto:hiring@newtendermint.org)!

[bft]: https://en.wikipedia.org/wiki/Byzantine_fault_tolerance
[smr]: https://en.wikipedia.org/wiki/State_machine_replication
[Blockchain]: https://en.wikipedia.org/wiki/Blockchain
[version-badge]: https://img.shields.io/github/tag/tendermint/tendermint.svg
[version-url]: https://github.com/tendermint/tendermint/releases/latest
[api-badge]: https://camo.githubusercontent.com/915b7be44ada53c290eb157634330494ebe3e30a/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f676f6c616e672f6764646f3f7374617475732e737667
[api-url]: https://pkg.go.dev/github.com/tendermint/tendermint
[go-badge]: https://img.shields.io/badge/go-1.18-blue.svg
[go-url]: https://github.com/moovweb/gvm
[discord-badge]: https://img.shields.io/discord/669268347736686612.svg
[discord-url]: https://discord.gg/cosmosnetwork
[license-badge]: https://img.shields.io/github/license/tendermint/tendermint.svg
[license-url]: https://github.com/tendermint/tendermint/blob/main/LICENSE
[sg-badge]: https://sourcegraph.com/github.com/tendermint/tendermint/-/badge.svg
[sg-url]: https://sourcegraph.com/github.com/tendermint/tendermint?badge
[tests-url]: https://github.com/tendermint/tendermint/actions/workflows/tests.yml
[tests-badge]: https://github.com/tendermint/tendermint/actions/workflows/tests.yml/badge.svg?branch=main
[lint-badge]: https://github.com/tendermint/tendermint/actions/workflows/lint.yml/badge.svg
[lint-url]: https://github.com/tendermint/tendermint/actions/workflows/lint.yml


The Best Go Libraries For Blockchain - Blockchain (12)

gno