feat: scoped accounts

inputs.schema.json

@@ -22,13 +22,13 @@
   "definitions": {
     "Balances": {
       "type": "array",
-      "description": "List of account balances. The (account, asset, color) triple of each entry must be unique within the list.",
+      "description": "List of account balances. The (account, asset, color, scope) tuple of each entry must be unique within the list.",
       "items": { "$ref": "#/definitions/BalanceRow" }
     },
 
     "BalanceRow": {
       "type": "object",
-      "description": "The balance of a given (account, asset, color)",
+      "description": "The balance of a given (account, asset, color, scope)",
       "additionalProperties": false,
       "required": ["account", "asset", "amount"],
       "properties": {
@@ -46,6 +46,10 @@
         "color": {
           "type": "string",
           "pattern": "^[A-Z]*$"
+        },
+        "scope": {
+          "type": "string",
+          "pattern": "^[a-z0-9_]*$"
         }
       }
     },
@@ -60,13 +64,30 @@
     },
 
     "AccountsMetadata": {
+      "type": "array",
+      "description": "List of account metadata entries. The (account, key, scope) tuple of each entry must be unique within the list.",
+      "items": { "$ref": "#/definitions/AccountMetadataRow" }
+    },
+
+    "AccountMetadataRow": {
       "type": "object",
-      "description": "Map of an account metadata to the account's metadata",
+      "description": "A single metadata entry: the value of a given (account, key, scope)",
       "additionalProperties": false,
-      "patternProperties": {
-        "^([a-zA-Z0-9_-]+(:[a-zA-Z0-9_-]+)*)$": {
-          "type": "object",
-          "additionalProperties": { "type": "string" }
+      "required": ["account", "key", "value"],
+      "properties": {
+        "account": {
+          "type": "string",
+          "pattern": "^([a-zA-Z0-9_-]+(:[a-zA-Z0-9_-]+)*)$"
+        },
+        "key": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string",
+          "pattern": "^[a-z0-9_]*$"
         }
       }
     },

internal/analysis/check.go

@@ -54,13 +54,19 @@ func (StatementFnCallResolution) fnCallResolution() {}
 func (r VarOriginFnCallResolution) GetParams() []string { return r.Params }
 func (r StatementFnCallResolution) GetParams() []string { return r.Params }
 
-const FnSetTxMeta = "set_tx_meta"
-const FnSetAccountMeta = "set_account_meta"
-const FnVarOriginMeta = "meta"
-const FnVarOriginBalance = "balance"
-const FnVarOriginOverdraft = "overdraft"
-const FnVarOriginGetAsset = "get_asset"
-const FnVarOriginGetAmount = "get_amount"
+const (
+	// Statemetn fns
+	FnSetTxMeta      = "set_tx_meta"
+	FnSetAccountMeta = "set_account_meta"
+
+	// Expr fns
+	FnVarOriginMeta      = "meta"
+	FnVarOriginBalance   = "balance"
+	FnVarOriginOverdraft = "overdraft"
+	FnVarOriginGetAsset  = "get_asset"
+	FnVarOriginGetAmount = "get_amount"
+	FnVarOriginScoped    = "scoped"
+)
 
 var Builtins = map[string]FnCallResolution{
 	FnSetTxMeta: StatementFnCallResolution{
@@ -114,6 +120,17 @@ var Builtins = map[string]FnCallResolution{
 			},
 		},
 	},
+	FnVarOriginScoped: VarOriginFnCallResolution{
+		Params: []string{TypeAccount, TypeString},
+		Return: TypeAccount,
+		Docs:   "returns the scoped version of that account. Empty string means no scope. Overwrites the previous scope",
+		VersionConstraints: []VersionClause{
+			{
+				Version:     parser.NewVersionInterpreter(0, 0, 25),
+				FeatureFlag: flags.ExperimentalScopedFunction,
+			},
+		},
+	},
 }
 
 type Diagnostic struct {

internal/cmd/run.go

@@ -58,15 +58,27 @@ func run(scriptPath string, opts RunArgs) error {
 	}
 
 	// Reject a malformed inputs file before running anything: a balance list is a
-	// map keyed by (account, asset, color), so a repeated key is ambiguous.
+	// map keyed by (account, asset, color, scope), so a repeated key is ambiguous.
 	if dup, ok := inputs.Balances.FirstDuplicate(); ok {
 		key := fmt.Sprintf("account=%q asset=%q", dup.Account, dup.Asset)
 		if dup.Color != "" {
 			key += fmt.Sprintf(" color=%q", dup.Color)
 		}
+		if dup.Scope != "" {
+			key += fmt.Sprintf(" scope=%q", dup.Scope)
+		}
 		return fmt.Errorf("invalid inputs file '%s': balances must not contain duplicate entries: duplicate entry for %s", inputsPath, key)
 	}
 
+	// Likewise, a metadata list is keyed by (account, key, scope).
+	if dup, ok := inputs.Meta.FirstDuplicate(); ok {
+		key := fmt.Sprintf("account=%q key=%q", dup.Account, dup.Key)
+		if dup.Scope != "" {
+			key += fmt.Sprintf(" scope=%q", dup.Scope)
+		}
+		return fmt.Errorf("invalid inputs file '%s': metadata must not contain duplicate entries: duplicate entry for %s", inputsPath, key)
+	}
+
 	featureFlags := map[string]struct{}{}
 	for _, flag := range inputs.FeatureFlags {
 		featureFlags[flag] = struct{}{}

internal/cmd/test_init.go

@@ -117,7 +117,7 @@ func makeSpecsFile(
 		DefaultBalance: defaultBalance,
 		StaticStore: interpreter.StaticStore{
 			Balances: interpreter.Balances{},
-			Meta:     make(interpreter.AccountsMetadata),
+			Meta:     interpreter.AccountsMetadata{},
 		},
 	}
 

internal/flags/flags.go

@@ -6,6 +6,7 @@ const (
 	ExperimentalOverdraftFunctionFeatureFlag FeatureFlag = "experimental-overdraft-function"
 	ExperimentalGetAssetFunctionFeatureFlag  FeatureFlag = "experimental-get-asset-function"
 	ExperimentalGetAmountFunctionFeatureFlag FeatureFlag = "experimental-get-amount-function"
+	ExperimentalScopedFunction               FeatureFlag = "experimental-scoped-function"
 	ExperimentalOneofFeatureFlag             FeatureFlag = "experimental-oneof"
 	ExperimentalAccountInterpolationFlag     FeatureFlag = "experimental-account-interpolation"
 	ExperimentalMidScriptFunctionCall        FeatureFlag = "experimental-mid-script-function-call"
@@ -17,6 +18,7 @@ var AllFlags []string = []string{
 	ExperimentalOverdraftFunctionFeatureFlag,
 	ExperimentalGetAssetFunctionFeatureFlag,
 	ExperimentalGetAmountFunctionFeatureFlag,
+	ExperimentalScopedFunction,
 	ExperimentalOneofFeatureFlag,
 	ExperimentalAccountInterpolationFlag,
 	ExperimentalMidScriptFunctionCall,

internal/interpreter/__snapshots__/accounts_metadata_test.snap

@@ -0,0 +1,13 @@
+
+[TestPrettyPrintAccountsMetadata/without_scope_(no_Scope_column) - 1]
+| Account | Name | Value    |
+| alice   | kyc  | verified |
+| bob     | tier | gold     |
+---
+
+[TestPrettyPrintAccountsMetadata/with_scope_(Scope_column_shown) - 1]
+| Account | Scope | Name | Value    |
+| alice   | eu    | kyc  | pending  |
+| alice   |       | kyc  | verified |
+| bob     |       | tier | gold     |
+---

internal/interpreter/accounts_metadata.go

@@ -1,53 +1,74 @@
 package interpreter
 
 import (
+	"slices"
+
 	"github.com/formancehq/numscript/internal/utils"
 )
 
-type AccountMetadata = map[string]string
-type AccountsMetadata map[string]AccountMetadata
-
-func (m AccountsMetadata) fetchAccountMetadata(account string) AccountMetadata {
-	return utils.MapGetOrPutDefault(m, account, func() AccountMetadata {
-		return AccountMetadata{}
-	})
-}
-
-func (m AccountsMetadata) DeepClone() AccountsMetadata {
-	cloned := make(AccountsMetadata)
-	for account, accountBalances := range m {
-		for asset, metadataValue := range accountBalances {
-			clonedAccountBalances := cloned.fetchAccountMetadata(account)
-			utils.MapGetOrPutDefault(clonedAccountBalances, asset, func() string {
-				return metadataValue
-			})
-		}
-	}
-	return cloned
+type AccountMetadataRow struct {
+	Account string `json:"account"`
+	Key     string `json:"key"`
+	Value   string `json:"value"`
+	Scope   string `json:"scope,omitempty"`
 }
 
-func (m AccountsMetadata) Merge(update AccountsMetadata) {
-	for acc, accBalances := range update {
-		cachedAcc := utils.MapGetOrPutDefault(m, acc, func() AccountMetadata {
-			return AccountMetadata{}
-		})
+// AccountsMetadata is the external, serialized representation of account
+// metadata. The runtime works with the in-memory InternalAccountsMetadata and
+// converts to this at the boundaries (store queries, execution result).
+type AccountsMetadata []AccountMetadataRow
 
-		for curr, amt := range accBalances {
-			cachedAcc[curr] = amt
+// FirstDuplicate returns the first row whose (account, key, scope) key already
+// appeared earlier in the list, if any. That triple is the identity of a
+// metadata entry and the value is its content, so a repeated key is an
+// ambiguous, malformed input.
+func (rows AccountsMetadata) FirstDuplicate() (AccountMetadataRow, bool) {
+	seen := make(map[[3]string]struct{}, len(rows))
+	for _, row := range rows {
+		key := [3]string{row.Account, row.Key, row.Scope}
+		if _, ok := seen[key]; ok {
+			return row, true
 		}
+		seen[key] = struct{}{}
 	}
+	return AccountMetadataRow{}, false
 }
 
 func (m AccountsMetadata) PrettyPrint() string {
-	header := []string{"Account", "Name", "Value"}
+	// the Scope column is shown only when at least one entry has a scope
+	hasScope := slices.ContainsFunc(m, func(row AccountMetadataRow) bool {
+		return row.Scope != ""
+	})
+
+	var header []string
+	if hasScope {
+		header = []string{"Account", "Scope", "Name", "Value"}
+	} else {
+		header = []string{"Account", "Name", "Value"}
+	}
 
 	var rows [][]string
-	for account, accMetadata := range m {
-		for name, value := range accMetadata {
-			row := []string{account, name, value}
-			rows = append(rows, row)
+	for _, row := range m {
+		if hasScope {
+			rows = append(rows, []string{row.Account, row.Scope, row.Key, row.Value})
+		} else {
+			rows = append(rows, []string{row.Account, row.Key, row.Value})
 		}
 	}
 
 	return utils.CsvPretty(header, rows, true)
 }
+
+// CompareAccountsMetadata reports whether two metadata lists hold the same set
+// of rows, ignoring order.
+func CompareAccountsMetadata(a AccountsMetadata, b AccountsMetadata) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for _, row := range a {
+		if !slices.Contains(b, row) {
+			return false
+		}
+	}
+	return true
+}

internal/interpreter/accounts_metadata_test.go

@@ -0,0 +1,28 @@
+package interpreter
+
+import (
+	"testing"
+
+	"github.com/gkampitakis/go-snaps/snaps"
+)
+
+func TestPrettyPrintAccountsMetadata(t *testing.T) {
+	t.Run("without scope (no Scope column)", func(t *testing.T) {
+		meta := AccountsMetadata{
+			{Account: "alice", Key: "kyc", Value: "verified"},
+			{Account: "bob", Key: "tier", Value: "gold"},
+		}
+
+		snaps.MatchSnapshot(t, meta.PrettyPrint())
+	})
+
+	t.Run("with scope (Scope column shown)", func(t *testing.T) {
+		meta := AccountsMetadata{
+			{Account: "alice", Key: "kyc", Value: "verified"},
+			{Account: "alice", Scope: "eu", Key: "kyc", Value: "pending"},
+			{Account: "bob", Key: "tier", Value: "gold"},
+		}
+
+		snaps.MatchSnapshot(t, meta.PrettyPrint())
+	})
+}

internal/interpreter/append_scope.go

@@ -0,0 +1,11 @@
+package interpreter
+
+import (
+	"regexp"
+)
+
+var scopeRegex = regexp.MustCompile(`^[a-z0-9_]*$`)
+
+func validateScope(scope string) bool {
+	return scopeRegex.MatchString(scope)
+}

internal/interpreter/append_scope_test.go

@@ -0,0 +1,36 @@
+package interpreter
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestAccountAddressString(t *testing.T) {
+	t.Run("no scope", func(t *testing.T) {
+		require.Equal(t, AccountAddress{Name: "acc"}.String(), "acc")
+	})
+
+	t.Run("with scope", func(t *testing.T) {
+		require.Equal(t, AccountAddress{Name: "acc", Scope: "xyz"}.String(), "acc/xyz")
+	})
+}
+
+func TestScopeValidation(t *testing.T) {
+	t.Run("valid scopes", func(t *testing.T) {
+		require.True(t, validateScope(""))
+		require.True(t, validateScope("myscope"))
+		require.True(t, validateScope("x"))
+		require.True(t, validateScope("x1"))
+		require.True(t, validateScope("my_scope_with_underscores"))
+	})
+
+	t.Run("invalid scopes", func(t *testing.T) {
+		require.False(t, validateScope("!"))
+		require.False(t, validateScope("$"))
+		require.False(t, validateScope("UPPERCASE"))
+		require.False(t, validateScope("dash-case"))
+		require.False(t, validateScope("colons:within"))
+	})
+
+}

internal/interpreter/args_parser_test.go

@@ -36,7 +36,7 @@ func TestParseValid(t *testing.T) {
 
 	p := NewArgsParser([]Value{
 		NewMonetaryInt(42),
-		AccountAddress("user:001"),
+		AccountAddress{Name: "user:001"},
 	})
 	a1 := parseArg(p, parser.Range{}, expectNumber)
 	a2 := parseArg(p, parser.Range{}, expectAccount)
@@ -48,15 +48,15 @@ func TestParseValid(t *testing.T) {
 	require.NotNil(t, a2, "a2 should not be nil")
 
 	require.Equal(t, a1, MonetaryInt(*big.NewInt(42)))
-	require.Equal(t, a2, AccountAddress("user:001"))
+	require.Equal(t, a2, AccountAddress{Name: "user:001"})
 }
 
 func TestParseBadType(t *testing.T) {
 	t.Parallel()
 
 	p := NewArgsParser([]Value{
 		NewMonetaryInt(42),
-		AccountAddress("user:001"),
+		AccountAddress{Name: "user:001"},
 	})
 	parseArg(p, parser.Range{}, expectMonetary)
 	parseArg(p, parser.Range{}, expectAccount)