Exploring Gno.land with gnoweb
gnoweb is Gno.land's universal web interface that lets you browse applications
and source code on any Gno.land network. This guide explains how to use gnoweb
to explore the blockchain ecosystem.
Networks
The main gnoweb instance is available at gno.land, which serves the Betanet (gnoland1). The Staging network is accessible at staging.gno.land.
For a complete list of all available networks (testnets and more), see Networks.
Understanding Code Organization
Before diving into gnoweb, we need to cover a fundamental concept in Gno.land:
code organization.
Gno.land can host two types of code: realms (smart contracts), and pure packages (libraries). Realms can contain and manage state, while pure packages are used for creating reusable functionality, hence pure.
Gno.land employs a storage system which is similar to a classic file system - each
package lives on a specific package path. A typical Gno.land package path, such
as gno.land/r/gnoland/home, contains the following components:
gno.land / r / gnoland / home
chain domain type namespace package name
Let's break it down:
chain domainrepresents the domain of the chain. In this case, the domain is simplygno.land. In the future, the ecosystem may expand to multiple chains which could have different chain domains.typerepresents the type of package found on this path. There are two available options -p&r- pure packages and realms, respectively.namespaceis the namespace of the package. Currently only address-prefix namespaces are supported, where the namespace matches the deployer's address.package namerepresents the name of the package found on the path. This part has to match the top-level package declaration in Gno files.
Viewing Rendered Content
Realms can implement a special Render() function that returns Markdown content:
gnoweb is a minimalistic web server that serves as a unified frontend for all
realms in Gno.land. It uses ABCI queries to get the latest state of a specific
realm from the Gno.land network.
Let's dive into how this works.
Realm state rendering
In line with minimalistic principles, Gno.land encourages developers to implement
a Render() function within their realms, allowing them to create a Markdown view
for how their realms will be rendered. gnoweb utilizes a built-in Markdown renderer
that uses the output of the Render() function as its content source.
A simple example of a realm utilizing the Render function can be found below:
package hello
func Render(path string) string {
if path == "" {
return "# Hello, 世界!"
}
return "# Hello, " + path
}
Based on the provided path, gnoweb queries the Gno.land network using the
qrender ABCI query. It then renders the response data as Markdown.
The realm above can be found on the Staging network at gno.land/r/docs/hello.
While JS/TS clients for Gno exist and developers can create custom websites for their
Gno.land applications as they see fit, the approach gnoweb takes with Render()
is a surefire way for simplicity and ease of development.
Render() is optionalDevelopers can but do not have to provide a Render() function in their realms.
Custom getter methods tailored to the specifics of the realm can be built instead.
Images and IPFS content
Rendered pages load images only from gnoweb's own assets, data: SVG images,
the IPFS gateway described below (with its *.ipfs. and *.ipns. subdomains
when it is named by a DNS host) and these hosts (cspImgHost in
gno.land/cmd/gnoweb/main.go):
gnolang.github.ioandsa.gno.servicesimgur.comand its subdomainsgithub.com,*.github.ioand*.githubusercontent.com
To show content stored on IPFS, use an ipfs://<cid>/<path> or
ipns://<name>/<path> URL as the target of a markdown link or image. gnoweb
resolves it through its configured IPFS gateway (-ipfs-gateway, Filebase's
public gateway by default). It also rewrites links and images that point at a
retired public gateway, such as ipfs.io or dweb.link, and images on Filebase's,
to the configured gateway, so a stored image follows a gateway change. Prefer
ipfs:// to a gateway URL, so the gateway can change without touching your
realm. The content still has to be pinned somewhere on the IPFS network: a
gateway only serves what some node provides.
The URL helpers in p/nt/markdown/sanitize/v0, which p/moul/md/v0 uses,
reject ipfs:// URLs, so write the markdown yourself for a CID your realm
controls. Never put a CID or URL that comes from users or other realms into
markdown as is: check that the CID contains only ASCII letters and digits, then
build ipfs://<cid> from it. If you add a path, allow only ASCII letters,
digits, -, _ and . in each segment, and reject . and .. segments.
Build the alt text or link label with sanitize.InlineText, as md.Image and
md.Link would.
Viewing source code
All code uploaded to Gno.land is open-source and available for everyone to see, by design.
Visit the gno.land/r/docs/source realm to learn
how you can do this.
Alternative: Terminal UI with gnobro
While gnoweb provides a web-based interface for exploring realms, developers
who prefer working in the terminal can use gnobro - a terminal user interface
(TUI) for browsing realms.
gnobro offers:
- Terminal-based navigation of realms
- Direct connection to
gnodevfor local development - Real-time updates when connected to a development server
- SSH access for remote browsing
To learn more about gnobro, see the gnobro
documentation.