Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.

Playground

dev.gno

// Package dev is the chain as a Plan 9 device tree.
//
// In Plan 9 a device is not storage, it is code behind a name: reading
// /dev/time runs a function. Everything a gno realm normally reaches through
// an import of chain/runtime is published here as a file instead, so it can be
// read, listed, bound and unioned like anything else:
//
//	cat /dev/sysname     the chain id
//	cat /dev/height      the block height
//	cat /dev/session     what a delegated key is allowed to touch
//
// The tree is posted to gno.land/r/moul/x/plan9/ns's /srv at deploy time, so
// any account can bind it into their own namespace, and nobody has to import
// this realm to use it. That is the cross-realm mount the whole experiment
// turns on: an interface value published by one realm, stored by another, and
// called later from a read-only Render.
//
// It is READ-ONLY, like every synthetic tree: the files have no Write, so
// grafting this into a stranger's namespace cannot be turned into a write
// against this realm.
//
// /dev/session is the one to look at. A gno.land account session is a
// delegated key scoped to a list of path prefixes, which is Plan 9's "the
// namespace IS the capability" rediscovered thirty-four years later. Printing
// it as a file makes that visible.
//
// NOTICE. Plan 9 from Bell Labs is the work of the Computing Science Research
// Center at Bell Labs; the name and the marks are theirs, and the copyright is
// held by the Plan 9 Foundation (https://p9f.org). This realm is not
// affiliated with, endorsed by, or sponsored by them, and contains no Plan 9
// code: it borrows the vocabulary so that the design reads without a glossary,
// and it is an homage, asking what that ecosystem's spirit looks like on a
// chain. Full attribution: NOTICE.md at the root of moul/gno-contracts.
package dev

import (
	"chain/runtime"
	"chain/runtime/unsafe"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"

	"gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/kit/ui/v0"
	"gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/md/v0"
	ninep "gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/ninep/v0"
	synfs "gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/synfs/v0"

	nsrealm "gno.land/r/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/ns/v1"
)

var tree *synfs.Tree

// docs describes each device, for Render and for /dev/drivers.
var docs = [][2]string{
	{"caller", "pkgpath of the realm that crossed into this read"},
	{"domain", "the chain domain"},
	{"drivers", "this table"},
	{"height", "current block height"},
	{"null", "always empty; the bit bucket"},
	{"random", "sha256 of chain id and height, hex; block-deterministic, NOT unpredictable"},
	{"session", "the calling key's session scope, one AllowPath per line"},
	{"sysname", "the chain id"},
	{"time", "block time, RFC3339"},
	{"user", "the origin caller's address"},
	{"zero", "endless NUL bytes; reads exactly what you ask for"},
}

func init(cur realm) {
	tree = build()
	nsrealm.Post(cross(cur), "dev", tree.Root())
}

func build() *synfs.Tree {
	t := synfs.New("dev", "sys", func() int64 { return runtime.ChainHeight() })
	r := t.Root()

	r.Add("sysname", func() string { return runtime.ChainID() })
	r.Add("domain", func() string { return runtime.ChainDomain() })
	r.Add("height", func() string { return strconv.FormatInt(runtime.ChainHeight(), 10) })
	r.Add("time", func() string { return time.Now().Format(time.RFC3339) })
	r.Add("user", func() string { return unsafe.OriginCaller().String() })
	r.Add("caller", func() string { return unsafe.PreviousRealm().PkgPath() })
	r.Add("null", func() string { return "" })
	r.Add("random", func() string {
		sum := sha256.Sum256([]byte(runtime.ChainID() + ":" +
			strconv.FormatInt(runtime.ChainHeight(), 10)))
		return hex.EncodeToString(sum[:])
	})
	r.Add("session", session)
	r.Add("drivers", drivers)

	// /dev/zero has no end, so it serves the read window itself rather than
	// materialising a value. An unbounded read returns nothing, which is what
	// stops `cat /dev/zero` from being a denial of service.
	r.AddRange("zero", 0444, func(off, count int64) (string, error) {
		if count <= 0 {
			return "", nil
		}
		if count > 4096 {
			count = 4096
		}
		return strings.Repeat("\x00", int(count)), nil
	})
	return t
}

// session prints the calling key's authority. A plain key has none, which is
// itself worth saying out loud.
func session() string {
	pubKeyAddr, expiresAt, allowPaths, isSession := runtime.GetSessionInfo()
	if !isSession {
		var b strings.Builder
		b.WriteString("session no\n")
		b.WriteString("scope full\n")
		return b.String()
	}
	var b strings.Builder
	b.WriteString("session yes\n")
	b.WriteString("key " + pubKeyAddr.String() + "\n")
	b.WriteString("expires " + strconv.FormatInt(expiresAt, 10) + "\n")
	for _, p := range allowPaths {
		b.WriteString("allow " + p + "\n")
	}
	return b.String()
}

func drivers() string {
	var b strings.Builder
	for _, d := range docs {
		b.WriteString(d[0] + "\t" + d[1] + "\n")
	}
	return b.String()
}

// Root returns the device tree, for a realm that would rather import it than
// bind it. Reading it is safe from anywhere; it has no mutating method.
func Root() ninep.File { return tree.Root() }

// Render lists the devices, or reads one.
//
//	Render("")            the table of devices
//	Render("cat/height")  one device's contents
func Render(path string) string {
	parts := strings.Split(strings.Trim(path, "/"), "/")
	if len(parts) >= 2 && parts[0] == "cat" {
		name := parts[1]
		f, err := tree.Root().Walk(name)
		if err != nil {
			return "# /dev/" + ui.Inline(name) + "\n\n" + md.CodeBlock(err.Error())
		}
		data, err := ninep.ReadAll(f)
		if err != nil {
			return "# /dev/" + ui.Inline(name) + "\n\n" + md.CodeBlock(err.Error())
		}
		return "# /dev/" + ui.Inline(name) + "\n\n" + md.CodeBlock(strings.TrimSuffix(data, "\n")) + "\n[all devices](/r/moul/x/plan9/dev/v1)\n"
	}
	return renderIndex()
}

func renderIndex() string {
	var b strings.Builder
	b.WriteString("# /dev\n\n")
	b.WriteString("The chain as a Plan 9 device tree. Each file is a function: reading it ")
	b.WriteString("runs code, so `/dev/height` is never stale.\n\n")
	b.WriteString("Posted to [`r/moul/x/plan9/ns`](/r/moul/x/plan9/ns/v1)'s `/srv` at deploy ")
	b.WriteString("time, so no realm has to import this one to use it:\n\n")
	b.WriteString("```\nbind /srv/dev /dev\n```\n\n")
	b.WriteString("| device | contents |\n|---|---|\n")
	for _, d := range docs {
		b.WriteString("| [`" + d[0] + "`](/r/moul/x/plan9/dev/v1:cat/" + d[0] + ") | " + d[1] + " |\n")
	}
	b.WriteString("\nDesign and analysis: ")
	b.WriteString("[moul/gno-contracts#136](https://github.com/moul/gno-contracts/issues/136).\n")
	b.WriteString("\n_Not affiliated with Plan 9. Plan 9 from Bell Labs is the ")
	b.WriteString("work of the Computing Science Research Center at Bell Labs; the name ")
	b.WriteString("and the marks are theirs, and the copyright is held by the ")
	b.WriteString("[Plan 9 Foundation](https://p9f.org). This realm borrows the ")
	b.WriteString("vocabulary and none of the code: it is an homage, asking what that ")
	b.WriteString("ecosystem's spirit looks like on a chain._\n")
	return b.String()
}

dev_test.gno

package dev

import (
	"chain/runtime"
	"strconv"
	"strings"
	"testing"

	"gno.land/p/nt/testutils/v0"
	"gno.land/p/nt/uassert/v0"

	ninep "gno.land/p/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/ninep/v0"

	nsrealm "gno.land/r/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/ns/v1"
)

func read(t *testing.T, name string) string {
	t.Helper()
	f, err := tree.Root().Walk(name)
	if err != nil {
		t.Fatalf("walk %s: %v", name, err)
	}
	data, err := ninep.ReadAll(f)
	if err != nil {
		t.Fatalf("read %s: %v", name, err)
	}
	return data
}

func TestDevicesFollowTheChain(t *testing.T) {
	if got, want := read(t, "sysname"), runtime.ChainID(); got != want {
		t.Errorf("sysname: got %q, want %q", got, want)
	}
	if got, want := read(t, "domain"), runtime.ChainDomain(); got != want {
		t.Errorf("domain: got %q, want %q", got, want)
	}
	if got, want := read(t, "height"), strconv.FormatInt(runtime.ChainHeight(), 10); got != want {
		t.Errorf("height: got %q, want %q", got, want)
	}

	// A device is code, not storage: advance the chain and the file follows.
	before := read(t, "height")
	testing.SkipHeights(5)
	after := read(t, "height")
	if before == after {
		t.Errorf("height did not move: %q", after)
	}
	b, _ := strconv.ParseInt(before, 10, 64)
	a, _ := strconv.ParseInt(after, 10, 64)
	if a-b != 5 {
		t.Errorf("height moved by %d, want 5", a-b)
	}
}

func TestRandomIsBlockDeterministic(t *testing.T) {
	a := read(t, "random")
	if len(a) != 64 {
		t.Errorf("a sha256 in hex is 64 characters, got %d", len(a))
	}
	if a != read(t, "random") {
		t.Error("two reads in the same block must agree, or Render is a consensus bug")
	}
	testing.SkipHeights(1)
	if a == read(t, "random") {
		t.Error("the value should change with the block")
	}
}

func TestNullAndZero(t *testing.T) {
	if got := read(t, "null"); got != "" {
		t.Errorf("null: %q", got)
	}
	f, _ := tree.Root().Walk("zero")
	got, _ := f.Read(0, 4)
	if got != "\x00\x00\x00\x00" {
		t.Errorf("zero: %q", got)
	}
	// An endless file must not answer an unbounded read with an endless value.
	if got, _ := f.Read(0, -1); got != "" {
		t.Errorf("unbounded read of /dev/zero: %d bytes", len(got))
	}
	if got, _ := f.Read(0, 1<<20); len(got) != 4096 {
		t.Errorf("a huge read should cap at 4096, got %d", len(got))
	}
}

func TestSessionReportsAPlainKey(t *testing.T) {
	got := read(t, "session")
	if got != "session no\nscope full\n" {
		t.Errorf("a plain key has no session scope: %q", got)
	}
}

func TestDriversListsEveryDevice(t *testing.T) {
	got := read(t, "drivers")
	ents, err := tree.Root().ReadDir()
	if err != nil {
		t.Fatalf("readdir: %v", err)
	}
	for _, e := range ents {
		if !strings.Contains(got, e.Name+"\t") {
			t.Errorf("/dev/drivers does not document %q", e.Name)
		}
	}
	if len(ents) != len(docs) {
		t.Errorf("%d devices but %d documented", len(ents), len(docs))
	}
}

func TestTreeIsReadOnly(t *testing.T) {
	var f ninep.File = tree.Root()
	if _, ok := f.(ninep.Mutable); ok {
		t.Error("a device tree handed to other realms must not be Mutable")
	}
}

// TestPostedAtDeployTime is the cross-realm claim the whole suite rests on:
// this realm pushed an interface value into another realm at init, and that
// realm can call it back later from a read.
func TestPostedAtDeployTime(t *testing.T) {
	found := false
	for _, s := range nsrealm.Services() {
		if s == "dev" {
			found = true
		}
	}
	if !found {
		t.Fatalf("dev is not posted in /srv: %v", nsrealm.Services())
	}
}

func TestAFreshNamespaceHasDevBound(cur realm, t *testing.T) {
	user := testutils.TestAddress("glenda")
	testing.SetRealm(testing.NewUserRealm(user))
	nsrealm.Reset(cross(cur))
	// Touch the namespace so it is built with /dev already bound.
	nsrealm.Exec(cross(cur), "echo hi > /tmp/hi")

	out, err := nsrealm.Run(user.String(), "ls /dev")
	if err != nil {
		t.Fatalf("ls /dev: %v", err)
	}
	for _, d := range docs {
		if !strings.Contains(out, d[0]) {
			t.Errorf("ls /dev is missing %q: %q", d[0], out)
		}
	}
	got, err := nsrealm.Run(user.String(), "cat /dev/sysname")
	if err != nil {
		t.Fatalf("cat: %v", err)
	}
	if got != runtime.ChainID() {
		t.Errorf("reading this realm's device through another realm's namespace: %q", got)
	}
	// And the mount table says where it came from.
	if ns := nsrealm.Namespace(user.String()); !strings.Contains(ns, "bind /srv/dev /dev") {
		t.Errorf("mount table: %q", ns)
	}
}

// The device name comes from the URL: escaped in the heading.
func TestDeviceNameIsEscaped(t *testing.T) {
	// No slash in the payload: Render splits the path on "/".
	out := Render("cat/x` [claim](evil.example) `")
	uassert.False(t, strings.Contains(out, "[claim](evil.example)"), out)
}

gnomod.toml

module = "gno.land/r/g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv/x/plan9/dev/v1"
gno = "0.9"

[addpkg]
  creator = "g1magld5ptgzaktqcexxq0pgq5lmdf0kz6re8hlv"
  height = 915402
  max_deposit = "8000000ugnot"

render_example_test.gno

package dev

// ExampleRender pins the device index. It carries no chain value, so it does
// not move with the block height the way the devices themselves do.
func ExampleRender() {
	print(Render(""))
	// Output:
	// # /dev
	//
	// The chain as a Plan 9 device tree. Each file is a function: reading it runs code, so `/dev/height` is never stale.
	//
	// Posted to [`r/moul/x/plan9/ns`](/r/moul/x/plan9/ns/v1)'s `/srv` at deploy time, so no realm has to import this one to use it:
	//
	// ```
	// bind /srv/dev /dev
	// ```
	//
	// | device | contents |
	// |---|---|
	// | [`caller`](/r/moul/x/plan9/dev/v1:cat/caller) | pkgpath of the realm that crossed into this read |
	// | [`domain`](/r/moul/x/plan9/dev/v1:cat/domain) | the chain domain |
	// | [`drivers`](/r/moul/x/plan9/dev/v1:cat/drivers) | this table |
	// | [`height`](/r/moul/x/plan9/dev/v1:cat/height) | current block height |
	// | [`null`](/r/moul/x/plan9/dev/v1:cat/null) | always empty; the bit bucket |
	// | [`random`](/r/moul/x/plan9/dev/v1:cat/random) | sha256 of chain id and height, hex; block-deterministic, NOT unpredictable |
	// | [`session`](/r/moul/x/plan9/dev/v1:cat/session) | the calling key's session scope, one AllowPath per line |
	// | [`sysname`](/r/moul/x/plan9/dev/v1:cat/sysname) | the chain id |
	// | [`time`](/r/moul/x/plan9/dev/v1:cat/time) | block time, RFC3339 |
	// | [`user`](/r/moul/x/plan9/dev/v1:cat/user) | the origin caller's address |
	// | [`zero`](/r/moul/x/plan9/dev/v1:cat/zero) | endless NUL bytes; reads exactly what you ask for |
	//
	// Design and analysis: [moul/gno-contracts#136](https://github.com/moul/gno-contracts/issues/136).
	//
	// _Not affiliated with Plan 9. Plan 9 from Bell Labs is the work of the Computing Science Research Center at Bell Labs; the name and the marks are theirs, and the copyright is held by the [Plan 9 Foundation](https://p9f.org). This realm borrows the vocabulary and none of the code: it is an homage, asking what that ecosystem's spirit looks like on a chain._
}

// ExampleRender_cat pins one device read. /dev/drivers is the one device whose
// contents are fixed, which makes it the only one an example can assert; the
// chain-derived ones are checked against chain/runtime in dev_test.gno.
func ExampleRender_cat() {
	print(Render("cat/drivers"))
	// Output:
	// # /dev/drivers
	//
	// ```
	// caller	pkgpath of the realm that crossed into this read
	// domain	the chain domain
	// drivers	this table
	// height	current block height
	// null	always empty; the bit bucket
	// random	sha256 of chain id and height, hex; block-deterministic, NOT unpredictable
	// session	the calling key's session scope, one AllowPath per line
	// sysname	the chain id
	// time	block time, RFC3339
	// user	the origin caller's address
	// zero	endless NUL bytes; reads exactly what you ask for
	// ```
	//
	// [all devices](/r/moul/x/plan9/dev/v1)
}