fix(examples): meta2

docs/resources/gno-interrealm.md

@@ -1,5 +1,25 @@
 # Interrealm Specification
 
+## Introduction
+
+XXX short intro on realms.
+XXX comparison to kernel syscalls, but cross-user.
+XXX simple code example.
+
+## Realm Finalization
+
+A realm boundary is defined as a change in realm in the call frame stack
+from one realm to another, whether explicitly crossed with `cross(fn)()`
+or implictly borrow-crossed into a different receiver's storage realm.
+A realm may cross into itself with an explicit cross-call.
+
+When returning from a realm boundary, all new reachable objects are assigned
+object IDs and stored in the current realm, ref-count-zero objects deleted
+(full "disk-persistent cycle GC" will come after launch) and any modified
+ref-count and Merkle hash root computed. This is called realm finalization.
+
+## `cross(fn)()` and `crossing()`
+
 Gno extends Go's type system with interrealm rules. These rules can be
 checked during the static type-checking phase (but at the moment they are
 partially dependent on runtime checks).
@@ -30,7 +50,8 @@ A crossing function declared in a realm different than the last explicitly
 crossed realm *must* be called like `cross(fn)(...)`. That is, functions of
 calls that result in explicit realm crossings must be wrapped with `cross()`.
 
-`std.CurrentRealm()` returns the current realm last explicitly crossed to.
+`std.CurrentRealm()` returns the current realm that was last explicitly crossed
+to.
 
 `std.PreviousRealm()` returns the realm explicitly crossed to before that.
 
@@ -59,7 +80,7 @@ receiver (and in general anything reachable is readable).
 New unreal objects reachable from the borrowed realm (or current realm if there
 was no method call that borrowed) become persisted in the borrowed realm (or
 current realm) upon finalization of the foreign object's method (or function).
-(When you put an unlabeled photo in someone else's scrap book the photo now
+(When you put an unlabeled photo in someone else's scrapbook the photo now
 belongs to the other person). In the future we will introduce an `attach()`
 function to prevent a new unreal object from being taken.
 
@@ -72,7 +93,7 @@ A realm package's initialization (including `init()` calls) execute with current
 realm of itself, and it `std.PreviousRealm()` will panic unless the call stack
 includes a crossing function called like `cross(fn)(...)`.
 
-### Justifications
+### `cross` and `crossing` Design Goals
 
 P package code should behave the same even when copied verbatim in a realm
 package.
@@ -107,7 +128,42 @@ be upgraded.
 Both `crossing()` and `cross(fn)(...)` statements may become special syntax in
 future Gno versions.
 
-### Usage
+## `attach()`
+
+## `panic()` and `revive(fn)`
+
+`panic()` behaves the same within the same realm boundary, but when a panic
+crosses a realm boundary (as defined in [Realm
+Finalization](#realm-finalization)) the Machine aborts the program. This is
+because in a multi-user environment it isn't safe to let the caller recover
+from realm panics that often leave the state in an invalid state.
+
+This would be sufficient, but we also want to write our tests to be able
+to detect such aborts and make assertions. For this reason Gno provides
+the `revive(fn)` builtin.
+
+```go
+abort := revive(func() {
+    cross(func() {
+        crossing()
+        panic("cross-realm panic")
+    })
+})
+abort == "cross-realm panic"
+```
+
+`revive(fn)` will execute 'fn' and return the exception that crossed
+a realm finalization boundary.
+
+This is only enabled in testing mode (for now), behavior is only partially
+implemented. In the future `revive(fn)` will be available for non-testing code,
+and the behavior will change such that `fn()` is run in transactional
+(cache-wrapped) memory context and any mutations discarded if and only if there
+was an abort.
+
+TL;DR: `revive(fn)` is Gno's builtin for STM (software transactional memory).
+
+## Application
 
 P package code cannot contain crossing functions, nor use `crossing()`. P
 package code also cannot import R realm packages. But code can call named
@@ -126,8 +182,8 @@ realms.
 
 Generally you want your methods to be non-crossing. Because they should work
 for everyone. They are functions that are pre-bound to an object, and that
-object is like a quasi-realm in itself, that could reside and migrate to other
-realms possibly. This is consistent with any p code copied over to r realms;
+object is like a quasi-realm in itself, that could possibly reside and migrate
+to other realms. This is consistent with any p code copied over to r realms;
 none of those methods would be crossing, and behavior would be the same; stored
 in any realm, mostly non-crossing methods that anyone can call. Why is a
 quasi-realm self-encapsulated Object in need to modify the realm in which it is
@@ -143,10 +199,10 @@ stdlibs functions are available unless overridden by the latter.
 `std.CurrentRealm()` shifts to `std.PreviousRealm()` if and only if a function
 is called like `cross(fn)(...)`.
 
-#### MsgCall
+### MsgCall
 
 MsgCall may only call crossing functions. This is to prevent potential
-confusion of non-sophisticated users. Non-crossing calls of non-crossing
+confusion for non-sophisticated users. Non-crossing calls of non-crossing
 functions of other realms is still possible with MsgRun.
 
 ```go
@@ -180,7 +236,7 @@ func AnotherPublic() {
 }
 ```
 
-#### MsgRun
+### MsgRun
 
 ```go
 // PKGPATH: gno.land/r/g1user/run
@@ -259,12 +315,12 @@ Therefore in the MsgRun file's `init()` function the previous realm and current
 realm have different pkgpaths (the origin caller always has empty pkgpath) but
 the address is the same.
 
-#### MsgAddPackage
+### MsgAddPackage
 
 During MsgAddPackage `std.PreviousRealm()` refers to the package deployer both
 in global var decls as well as inside `init()` functions. After that the
 package deployer is no longer provided, so packages need to remember the
-deployer in the initialization if needed.
+deployer in the initialization phase if needed.
 
 ```go
 // PKGPATH: gno.land/r/test/test
@@ -314,7 +370,7 @@ only times that `std.CurrentRealm()` will return a p package path that starts
 with "/p/" instead of "/r/". The package is technically still mutable during
 initialization.
 
-#### Testing overrides with stdlibs/testing
+### Testing overrides with stdlibs/testing
 
 The `gnovm/tests/stdlibs/testing/context_testing.gno` file provides functions
 for overriding frame details from Gno test code.
@@ -419,7 +475,7 @@ func main() {
 // XXX
 ```
 
-#### Future Work
+## Future Work
 
 `std.SetOriginCaller()` should maybe be deprecated in favor of
 `std.SetRealm(std.NewUserRealm(user))` renamed to

examples/Makefile

@@ -34,7 +34,7 @@ build:
 
 .PHONY: test
 test:
-	go run ../gnovm/cmd/gno test -v ./...
+	go run ../gnovm/cmd/gno test -v ./gno.land/...
 
 .PHONY: test.fast
 test.fast:

examples/gno.land/p/agherasie/forms/submit_test.gno

@@ -51,6 +51,7 @@ func TestAnswerForm(t *testing.T) {
 	urequire.True(t, len(db.Answers) == 1, "Expected 1 answer, got", string(len(db.Answers)))
 	urequire.True(t, db.Answers[0].FormID == formID, "Expected form ID", formID, "got", db.Answers[0].FormID)
 	urequire.True(t, db.Answers[0].Answers == answers, "Expected answers", answers, "got", db.Answers[0].Answers)
+	urequire.True(t, err == nil, "Submit should not return an error")
 }
 
 func TestAnswerFormDates(t *testing.T) {

examples/gno.land/p/demo/avl/z_0_filetest.gno

@@ -24,8 +24,6 @@ func main() {
 // Output:
 // false 2
 
-
-
 // Realm:
 // finalizerealm["gno.land/r/test"]
 // u[a8ada09dee16d791fd406d629fe29bb0ed084a30:7]=

examples/gno.land/p/demo/avl/z_1_filetest.gno

@@ -24,8 +24,6 @@ func main() {
 // Output:
 // false 3
 
-
-
 // Realm:
 // finalizerealm["gno.land/r/test"]
 // u[a8ada09dee16d791fd406d629fe29bb0ed084a30:9]=

examples/gno.land/p/demo/avl/z_2_filetest.gno

@@ -23,8 +23,6 @@ func main() {
 // Output:
 // false 3
 
-
-
 // Realm:
 // finalizerealm["gno.land/r/test"]
 // u[a8ada09dee16d791fd406d629fe29bb0ed084a30:10]=

examples/gno.land/p/demo/grc/grc20/tellers.gno

@@ -14,7 +14,7 @@ func (tok *Token) CallerTeller() Teller {
 
 	return &fnTeller{
 		accountFn: func() std.Address {
-			caller := std.CurrentRealm().Address()
+			caller := std.PreviousRealm().Address()
 			return caller
 		},
 		Token: tok,

examples/gno.land/p/demo/grc/grc20/tellers_test.gno

@@ -115,16 +115,21 @@ func TestCallerTeller(t *testing.T) {
 	checkBalances(1000, 0, 0)
 	checkAllowances(0, 0, 0, 0, 0, 0)
 
+	tellerThrough := func(action func()) {
+		testing.SetRealm(std.NewCodeRealm("gno.land/r/realm_exposing_the_teller"))
+		action()
+	}
+
 	testing.SetRealm(std.NewUserRealm(alice))
-	urequire.NoError(t, teller.Approve(bob, 600))
+	tellerThrough(func() { urequire.NoError(t, teller.Approve(bob, 600)) })
 	checkBalances(1000, 0, 0)
 	checkAllowances(600, 0, 0, 0, 0, 0)
 
 	testing.SetRealm(std.NewUserRealm(bob))
-	urequire.Error(t, teller.TransferFrom(alice, carl, 700))
+	tellerThrough(func() { urequire.Error(t, teller.TransferFrom(alice, carl, 700)) })
 	checkBalances(1000, 0, 0)
 	checkAllowances(600, 0, 0, 0, 0, 0)
-	urequire.NoError(t, teller.TransferFrom(alice, carl, 400))
+	tellerThrough(func() { urequire.NoError(t, teller.TransferFrom(alice, carl, 400)) })
 	checkBalances(600, 0, 400)
 	checkAllowances(200, 0, 0, 0, 0, 0)
 }

examples/gno.land/p/demo/ownable/exts/authorizable/authorizable.gno

@@ -55,7 +55,17 @@ func (a *Authorizable) AddToAuthList(addr std.Address) error {
 	if !a.OwnedByCurrent() {
 		return ErrNotSuperuser
 	}
+	return a.addToAuthList(addr)
+}
+
+func (a *Authorizable) AddToAuthListByPrevious(addr std.Address) error {
+	if !a.OwnedByPrevious() {
+		return ErrNotSuperuser
+	}
+	return a.addToAuthList(addr)
+}
 
+func (a *Authorizable) addToAuthList(addr std.Address) error {
 	if _, exists := a.authorized.Get(addr.String()); exists {
 		return ErrAlreadyInList
 	}
@@ -69,7 +79,17 @@ func (a *Authorizable) DeleteFromAuthList(addr std.Address) error {
 	if !a.OwnedByCurrent() {
 		return ErrNotSuperuser
 	}
+	return a.deleteFromAuthList(addr)
+}
 
+func (a *Authorizable) DeleteFromAuthListByPrevious(addr std.Address) error {
+	if !a.OwnedByPrevious() {
+		return ErrNotSuperuser
+	}
+	return a.deleteFromAuthList(addr)
+}
+
+func (a *Authorizable) deleteFromAuthList(addr std.Address) error {
 	if !a.authorized.Has(addr.String()) {
 		return ErrNotInAuthList
 	}
@@ -82,20 +102,33 @@ func (a *Authorizable) DeleteFromAuthList(addr std.Address) error {
 	return nil
 }
 
-func (a Authorizable) CallerOnAuthList() error {
-	caller := std.CurrentRealm().Address()
+func (a *Authorizable) OnAuthList() error {
+	current := std.CurrentRealm().Address()
+	return a.onAuthList(current)
+}
+
+func (a *Authorizable) PreviousOnAuthList() error {
+	previous := std.PreviousRealm().Address()
+	return a.onAuthList(previous)
+}
 
+func (a *Authorizable) onAuthList(caller std.Address) error {
 	if !a.authorized.Has(caller.String()) {
 		return ErrNotInAuthList
 	}
-
 	return nil
 }
 
 func (a Authorizable) AssertOnAuthList() {
-	caller := std.CurrentRealm().Address()
+	err := a.OnAuthList()
+	if err != nil {
+		panic(err)
+	}
+}
 
-	if !a.authorized.Has(caller.String()) {
-		panic(ErrNotInAuthList)
+func (a Authorizable) AssertPreviousOnAuthList() {
+	err := a.PreviousOnAuthList()
+	if err != nil {
+		panic(err)
 	}
 }

examples/gno.land/p/demo/ownable/exts/authorizable/authorizable_test.gno

@@ -35,20 +35,20 @@ func TestNewAuthorizableWithAddress(t *testing.T) {
 	}
 }
 
-func TestCallerOnAuthList(t *testing.T) {
+func TestOnAuthList(t *testing.T) {
 	a := NewAuthorizableWithAddress(alice)
 	testing.SetRealm(std.NewUserRealm(alice))
 
-	if err := a.CallerOnAuthList(); err == ErrNotInAuthList {
+	if err := a.OnAuthList(); err == ErrNotInAuthList {
 		t.Fatalf("expected alice to be on the list")
 	}
 }
 
-func TestNotCallerOnAuthList(t *testing.T) {
+func TestNotOnAuthList(t *testing.T) {
 	a := NewAuthorizableWithAddress(alice)
 	testing.SetRealm(std.NewUserRealm(bob))
 
-	if err := a.CallerOnAuthList(); err == nil {
+	if err := a.OnAuthList(); err == nil {
 		t.Fatalf("expected bob to not be on the list")
 	}
 }