feat(gno.land): add read-only metadata support to packages

docs/gno-tooling/cli/gnokey/querying-a-network.md

@@ -26,6 +26,7 @@ Below is a list of queries a user can make with `gnokey`:
 - `vm/qfile` - returns package contents for a given pkgpath
 - `vm/qeval` - evaluates an expression in read-only mode on and returns the results
 - `vm/qrender` - shorthand for evaluating `vm/qeval Render("")` for a given pkgpath
+- `vm/qmeta` - returns the value for a package metadata field
 
 Let's see how we can use them.
 
@@ -225,6 +226,14 @@ gnokey query vm/qrender --data "gno.land/r/demo/wugnot:balance/g125em6arxsnj49vx
 To see how this was achieved, check out `wugnot`'s `Render()` function.
 :::
 
+## `vm/qmeta`
+
+`vm/qmeta` allows us to read the metadata of a realm or package. For example:
+
+```bash
+gnokey query vm/qmeta --data "gno.land/r/demo/boards:field_name"`                     |
+```
+
 ## Conclusion
 
 That's it! 🎉

gno.land/pkg/keyscli/addpkg.go

@@ -4,6 +4,7 @@
 	"context"
 	"flag"
 	"fmt"
+	"strings"
 
 	"github.com/gnolang/gno/gno.land/pkg/sdk/vm"
 	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
@@ -21,6 +22,7 @@
 	PkgPath string
 	PkgDir  string
 	Deposit string
+	Meta    commands.StringArr
 }
 
 func NewMakeAddPkgCmd(rootCfg *client.MakeTxCfg, io commands.IO) *commands.Command {
@@ -62,6 +64,12 @@
 		"",
 		"deposit coins",
 	)
+
+	fs.Var(
+		&c.Meta,
+		"meta",
+		"metadata fields",
+	)
 }
 
 func execMakeAddPkg(cfg *MakeAddPkgCfg, args []string, io commands.IO) error {
@@ -107,6 +115,30 @@
 		panic(fmt.Sprintf("found an empty package %q", cfg.PkgPath))
 	}
 
+	// parse metadata fields
+	var metadata []*vm.MetaField //nolint: prealloc // Must be nil when there are no meta fields
+	for _, s := range cfg.Meta {
+		parts := strings.SplitN(s, "=", 2)
+		if len(parts) != 2 {
+			return errors.New("invalid metadata field format, expected field=value")
+		}
+
+		name := strings.TrimSpace(parts[0])
+		if name == "" {
+			return errors.New("empty metadata field name")
+		}
+
+		var value []byte
+		if v := parts[1]; strings.TrimSpace(v) != "" {
+			value = []byte(v)
+		}
+
+		metadata = append(metadata, &vm.MetaField{
+			Name:  name,
+			Value: value,
+		})
+	}
+
 	// parse gas wanted & fee.
 	gaswanted := cfg.RootCfg.GasWanted
 	gasfee, err := std.ParseCoin(cfg.RootCfg.GasFee)
@@ -115,9 +147,10 @@
 	}
 	// construct msg & tx and marshal.
 	msg := vm.MsgAddPackage{
-		Creator: creator,
-		Package: memPkg,
-		Deposit: deposit,
+		Creator:  creator,
+		Package:  memPkg,
+		Deposit:  deposit,
+		Metadata: metadata,
 	}
 	tx := std.Tx{
 		Msgs:       []std.Msg{msg},

gno.land/pkg/sdk/vm/errors.go

@@ -16,6 +16,7 @@
 // NOTE: these are meant to be used in conjunction with pkgs/errors.
 type (
 	InvalidPkgPathError   struct{ abciError }
+	InvalidPkgMetaError   struct{ abciError }
 	NoRenderDeclError     struct{ abciError }
 	PkgExistError         struct{ abciError }
 	InvalidStmtError      struct{ abciError }
@@ -28,6 +29,7 @@
 )
 
 func (e InvalidPkgPathError) Error() string   { return "invalid package path" }
+func (e InvalidPkgMetaError) Error() string   { return "invalid package metadata" }
 func (e NoRenderDeclError) Error() string     { return "render function not declared" }
 func (e PkgExistError) Error() string         { return "package already exists" }
 func (e InvalidStmtError) Error() string      { return "invalid statement" }
@@ -52,6 +54,10 @@
 	return errors.Wrap(InvalidPkgPathError{}, msg)
 }
 
+func ErrInvalidPkgMeta(msg string) error {
+	return errors.Wrap(InvalidPkgMetaError{}, msg)
+}
+
 func ErrInvalidStmt(msg string) error {
 	return errors.Wrap(InvalidStmtError{}, msg)
 }

gno.land/pkg/sdk/vm/handler.go

@@ -72,6 +72,7 @@
 	QueryFuncs  = "qfuncs"
 	QueryEval   = "qeval"
 	QueryFile   = "qfile"
+	QueryMeta   = "qmeta"
 )
 
 func (vh vmHandler) Query(ctx sdk.Context, req abci.RequestQuery) abci.ResponseQuery {
@@ -89,6 +90,8 @@
 		res = vh.queryEval(ctx, req)
 	case QueryFile:
 		res = vh.queryFile(ctx, req)
+	case QueryMeta:
+		res = vh.queryMeta(ctx, req)
 	default:
 		return sdk.ABCIResponseQueryFromError(
 			std.ErrUnknownRequest(fmt.Sprintf(
@@ -183,6 +186,23 @@
 	return
 }
 
+// queryMeta returns the value for a package metadata field.
+func (vh vmHandler) queryMeta(ctx sdk.Context, req abci.RequestQuery) (res abci.ResponseQuery) {
+	parts := strings.SplitN(string(req.Data), ":", 2)
+	if len(parts) != 2 {
+		panic("expected <pkgpath>:<field_name> syntax in query input data")
+	}
+
+	pkgPath, name := parts[0], parts[1]
+	result, err := vh.vm.QueryMeta(ctx, pkgPath, name)
+	if err != nil {
+		res = sdk.ABCIResponseQueryFromError(err)
+		return
+	}
+	res.Data = result
+	return
+}
+
 // ----------------------------------------
 // misc
 

gno.land/pkg/sdk/vm/keeper.go

@@ -5,6 +5,8 @@
 import (
 	"bytes"
 	"context"
+	"encoding/base64"
+	"encoding/json"
 	goerrors "errors"
 	"fmt"
 	"io"
@@ -37,11 +39,16 @@
 )
 
 const (
-	maxAllocTx    = 500_000_000
-	maxAllocQuery = 1_500_000_000 // higher limit for queries
-	maxGasQuery   = 3_000_000_000 // same as max block gas
+	maxAllocTx               = 500_000_000
+	maxAllocQuery            = 1_500_000_000 // higher limit for queries
+	maxGasQuery              = 3_000_000_000 // same as max block gas
+	maxMetaFieldValueSize    = 1_000_000     // maximum size for package metadata field values in bytes
+	maxMetaFields            = 10            // maximum number of package metadata fields
+	maxToolDescriptionLenght = 100
 )
 
+var reToolName = regexp.MustCompile(`^[a-z]+[_a-z0-9]{5,16}$`)
+
 // vm.VMKeeperI defines a module interface that supports Gno
 // smart contracts programming (scripting).
 type VMKeeperI interface {
@@ -354,6 +361,18 @@
 		return ErrTypeCheck(err)
 	}
 
+	// Set package metadata
+	for _, f := range msg.Metadata {
+		if f.Name == "tools" {
+			// The "tools" metadata field must have a valid pre-defined structure
+			if err := validateToolsMetaField(f.Value); err != nil {
+				return ErrInvalidPkgMeta(err.Error())
+			}
+		}
+
+		gnostore.SetPackageMetaField(msg.Package.Path, f.Name, f.Value)
+	}
+
 	// Pay deposit from creator.
 	pkgAddr := gno.DerivePkgAddr(pkgPath)
 
@@ -827,6 +846,27 @@
 	}
 }
 
+func (vm *VMKeeper) QueryMeta(ctx sdk.Context, pkgPath, name string) ([]byte, error) {
+	var (
+		res   []byte
+		store = vm.newGnoTransactionStore(ctx) // throwaway (never committed)
+	)
+
+	found := store.IteratePackageMeta(pkgPath, func(field string, value []byte) bool {
+		if field == name {
+			res = make([]byte, base64.StdEncoding.EncodedLen(len(value)))
+			base64.StdEncoding.Encode(res, value)
+			return true
+		}
+		return false
+	})
+
+	if !found {
+		return nil, fmt.Errorf("metadata field for package %s not found: %s", pkgPath, name) // TODO: XSS protection
+	}
+	return res, nil
+}
+
 // logTelemetry logs the VM processing telemetry
 func logTelemetry(
 	gasUsed int64,
@@ -858,3 +898,42 @@
 		metric.WithAttributes(attributes...),
 	)
 }
+
+func validateToolsMetaField(value []byte) error {
+	var v struct {
+		Tools []struct {
+			Name        string  `json:"name"`
+			Weight      float64 `json:"weight"`
+			Description string  `json:"description,omitempty"`
+		} `json:"tools,omitempty"`
+	}
+
+	if err := json.Unmarshal(value, &v); err != nil {
+		return fmt.Errorf("invalid tools field format: %w", err)
+	}
+
+	if len(v.Tools) == 0 {
+		return errors.New("tools list is empty")
+	}
+
+	var totalWeight float64
+	for _, t := range v.Tools {
+		if len(t.Description) > maxToolDescriptionLenght {
+			return fmt.Errorf("maximum length for tool description is %d", maxToolDescriptionLenght)
+		}
+
+		if !reToolName.MatchString(t.Name) {
+			return fmt.Errorf(
+				"invalid tool name: %s (minimum 6 chars, lowercase alphanumeric with underscore)",
+				t.Name,
+			)
+		}
+
+		totalWeight += t.Weight
+	}
+
+	if totalWeight != 1 {
+		return errors.New("the sum of all tool weights must be 1")
+	}
+	return nil
+}

gno.land/pkg/sdk/vm/msg_test.go

@@ -32,7 +32,7 @@ func TestMsgAddPackage_ValidateBasic(t *testing.T) {
 		{
 			name: "valid message",
 			msg:  NewMsgAddPackage(creator, pkgPath, files),
-			expectSignBytes: `{"creator":"g14ch5q26mhx3jk5cxl88t278nper264ces4m8nt","deposit":"",` +
+			expectSignBytes: `{"creator":"g14ch5q26mhx3jk5cxl88t278nper264ces4m8nt","deposit":"","metadata":null,` +
 				`"package":{"files":[{"body":"package test\n\t\tfunc Echo() string {return \"hello world\"}",` +
 				`"name":"test.gno"}],"name":"test","path":"gno.land/r/namespace/test"}}`,
 			expectErr: nil,

gno.land/pkg/sdk/vm/msgs.go

@@ -2,6 +2,7 @@
 
 import (
 	"fmt"
+	"regexp"
 	"strings"
 
 	"github.com/gnolang/gno/gnovm"
@@ -12,15 +13,26 @@
 	"github.com/gnolang/gno/tm2/pkg/std"
 )
 
+var reMetaFieldName = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`)
+
 //----------------------------------------
 // MsgAddPackage
 
-// MsgAddPackage - create and initialize new package
-type MsgAddPackage struct {
-	Creator crypto.Address    `json:"creator" yaml:"creator"`
-	Package *gnovm.MemPackage `json:"package" yaml:"package"`
-	Deposit std.Coins         `json:"deposit" yaml:"deposit"`
-}
+type (
+	// MsgAddPackage - create and initialize new package
+	MsgAddPackage struct {
+		Creator  crypto.Address    `json:"creator" yaml:"creator"`
+		Package  *gnovm.MemPackage `json:"package" yaml:"package"`
+		Deposit  std.Coins         `json:"deposit" yaml:"deposit"`
+		Metadata []*MetaField      `json:"metadata" yaml:"metadata"`
+	}
+
+	// MetaField - package metadata field
+	MetaField struct {
+		Name  string `json:"name" yaml:"name"`
+		Value []byte `json:"value" yaml:"value"`
+	}
+)
 
 var _ std.Msg = MsgAddPackage{}
 
@@ -60,6 +72,28 @@
 	if !msg.Deposit.IsValid() {
 		return std.ErrInvalidCoins(msg.Deposit.String())
 	}
+
+	if len(msg.Metadata) > maxMetaFields {
+		return ErrInvalidPkgMeta("maximum number of metadata fields exceeded")
+	}
+
+	seenFields := make(map[string]struct{}, len(msg.Metadata))
+	for _, f := range msg.Metadata {
+		if !reMetaFieldName.Match([]byte(f.Name)) {
+			return ErrInvalidPkgMeta("invalid metadata field name")
+		}
+
+		if _, exists := seenFields[f.Name]; exists {
+			return ErrInvalidPkgMeta("metadata contains duplicated fields")
+		}
+
+		if len(f.Value) > maxMetaFieldValueSize {
+			return ErrInvalidPkgMeta("metadata field value is too large")
+		}
+
+		seenFields[f.Name] = struct{}{}
+	}
+
 	// XXX validate files.
 	return nil
 }

gno.land/pkg/sdk/vm/package.go

@@ -18,8 +18,12 @@ var Package = amino.RegisterPackage(amino.NewPackage(
 	MsgRun{}, "m_run",
 	MsgAddPackage{}, "m_addpkg", // TODO rename both to MsgAddPkg?
 
+	// other
+	MetaField{}, "MetaField",
+
 	// errors
 	InvalidPkgPathError{}, "InvalidPkgPathError",
+	InvalidPkgMetaError{}, "InvalidPkgMetaError",
 	NoRenderDeclError{}, "NoRenderDeclError",
 	PkgExistError{}, "PkgExistError",
 	InvalidStmtError{}, "InvalidStmtError",