types.gno

 1package version_manager
 2
 3// VersionManager defines the interface for managing multiple versioned implementations of a domain.
 4// It switches implementations while retaining domain-owned storage. Each version
 5// is responsible for compatibility with that state and any required migration.
 6//
 7// Design Goals:
 8//   - Switch registered implementations without redeploying the domain
 9//   - Maintain a single source of truth for storage across all versions
10//   - Enforce security through domain-scoped registration
11//   - Retain registered versions for later activation, subject to state compatibility
12//
13// Implementation Note:
14// The actual implementations of each version must satisfy a common domain interface
15// defined by the specific domain (e.g., ProtocolFee interface for protocol_fee domain).
16type VersionManager interface {
17	// RegisterInitializer registers a version's implementation.
18	// Must be called by each version package during initialization.
19	// First registration becomes the active implementation.
20	// Subsequent registrations are retained for later switching.
21	//
22	// Parameters:
23	//   - _: Interrealm-call discriminator; callers pass 0.
24	//   - rlm: Propagated current realm context from the domain wrapper; implementations validate the current frame and inspect its previous frame to identify the registering version package.
25	//   - initializer: Callback receiving the discriminator, realm context, and domain storage wrapper, and returning that version's implementation instance.
26	//
27	// Returns:
28	//   - error: nil when the version is registered; otherwise an error for a spoofed or unauthorized caller, duplicate registration, or nil initializer.
29	RegisterInitializer(_ int, rlm realm, initializer func(_ int, rlm realm, store any) any) error
30
31	// ChangeImplementation switches the active version at runtime.
32	// The domain retains its KVStore; the selected initializer must handle state
33	// compatibility. The manager does not provide automatic schema migration.
34	//
35	// Parameters:
36	//   - _: Interrealm-call discriminator; callers pass 0.
37	//   - rlm: Propagated current realm context from the domain wrapper; implementations validate the current frame before switching.
38	//   - packagePath: Full package path of a version previously registered with RegisterInitializer.
39	//
40	// Returns:
41	//   - error: nil when the registered version becomes active; otherwise an error for a spoofed realm or unknown or invalid initializer.
42	ChangeImplementation(_ int, rlm realm, packagePath string) error
43
44	// GetDomainPath returns the base domain path (e.g., "gno.land/r/gnoswap/protocol_fee").
45	//
46	// Returns:
47	//   - string: Base package path used to scope this version manager's implementations.
48	GetDomainPath() string
49
50	// GetInitializers returns all registered version initializers.
51	//
52	// Returns:
53	//   - map[string]func(_ int, rlm realm, store any) any: Registry mapping each version package path to its initializer callback.
54	GetInitializers() map[string]func(_ int, rlm realm, store any) any
55
56	// GetCurrentPackagePath returns the package path of the active implementation.
57	//
58	// Returns:
59	//   - string: Package path of the active implementation, or the empty string before any version is registered.
60	GetCurrentPackagePath() string
61
62	// GetCurrentImplementation returns the active version instance.
63	// The caller should type-assert this to the domain-specific interface.
64	//
65	// Returns:
66	//   - any: Active version implementation instance, or nil before the first registration.
67	GetCurrentImplementation() any
68}