feat: Add node V3 opt-out metadata storage and management (#1074)

* feat: Add node V3 opt-out metadata storage and management

Implement storage and extrinsic for setting optional metadata on opted-out nodes (e.g. v4 account addresses). Add NodeV3OptOutMetadata storage map with 256-byte limit, set_node_v3_opt_out_metadata extrinsic callable by farm owner, and corresponding events NodeV3OptOutMetadataSet/Cleared. Include client methods GetNodeV3OptOutMetadata and SetNodeV3OptOutMetadata in Go and JS clients with comprehensive unit tests covering set, clear, authorization

---------

Author: sameh-farouk

clients/tfchain-client-go/events.go

@@ -350,6 +350,13 @@ type TwinAdminRemoved struct {
 	Topics  []types.Hash
 }
 
+type NodeV3OptOutMetadataUpdated struct {
+	Phase    types.Phase
+	NodeID   types.U32         `json:"node_id"`
+	Metadata types.OptionBytes `json:"metadata"`
+	Topics   []types.Hash
+}
+
 type EventSchedulerCallUnavailable struct {
 	Phase  types.Phase
 	Task   types.TaskAddress
@@ -489,6 +496,7 @@ type EventRecords struct {
 	TfgridModule_NodeV3BillingOptedOut         []NodeV3BillingOptedOut         //nolint:stylecheck,golint
 	TfgridModule_TwinAdminAdded                []TwinAdminAdded                //nolint:stylecheck,golint
 	TfgridModule_TwinAdminRemoved              []TwinAdminRemoved              //nolint:stylecheck,golint
+	TfgridModule_NodeV3OptOutMetadataUpdated   []NodeV3OptOutMetadataUpdated   //nolint:stylecheck,golint
 
 	// burn module events
 	BurningModule_BurnTransactionCreated []BurnTransactionCreated //nolint:stylecheck,golint

clients/tfchain-client-go/node.go

@@ -901,6 +901,62 @@ func (s *Substrate) GetNodeV3BillingOptOutTimestamp(nodeID uint32) (*uint64, err
 	return &ts, nil
 }
 
+// GetNodeV3OptOutMetadata returns the metadata stored for an opted-out node, or nil if not set.
+func (s *Substrate) GetNodeV3OptOutMetadata(nodeID uint32) ([]byte, error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return nil, err
+	}
+
+	bytes, err := Encode(nodeID)
+	if err != nil {
+		return nil, errors.Wrap(err, "substrate: encoding error building query arguments")
+	}
+
+	key, err := types.CreateStorageKey(meta, "TfgridModule", "NodeV3OptOutMetadata", bytes)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to create substrate query key")
+	}
+
+	raw, err := cl.RPC.State.GetStorageRawLatest(key)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to lookup node v3 opt-out metadata")
+	}
+
+	if len(*raw) == 0 {
+		return nil, nil
+	}
+
+	var metadata []byte
+	if err := Decode(*raw, &metadata); err != nil {
+		return nil, errors.Wrap(err, "failed to decode node v3 opt-out metadata")
+	}
+
+	return metadata, nil
+}
+
+// SetNodeV3OptOutMetadata sets metadata for an opted-out node (e.g. a v4 account address).
+// The node must already be opted out of v3 billing. Pass empty bytes to clear.
+// Only the farm owner can call this.
+func (s *Substrate) SetNodeV3OptOutMetadata(identity Identity, nodeID uint32, metadata []byte) (hash types.Hash, err error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return hash, err
+	}
+
+	c, err := types.NewCall(meta, "TfgridModule.set_node_v3_opt_out_metadata", nodeID, metadata)
+	if err != nil {
+		return hash, errors.Wrap(err, "failed to create call")
+	}
+
+	callResponse, err := s.Call(cl, meta, identity, c)
+	if err != nil {
+		return hash, errors.Wrap(err, "failed to set node v3 opt-out metadata")
+	}
+
+	return callResponse.Hash, nil
+}
+
 // SetNodeCertificate sets the node certificate type
 func (s *Substrate) SetNodeCertificate(identity Identity, id uint32, cert NodeCertification) error {
 	cl, meta, err := s.GetClient()

clients/tfchain-client-go/node_test.go

@@ -81,14 +81,74 @@ func TestOptOutOfV3Billing(t *testing.T) {
 	_, err = cl.OptOutOfV3Billing(identity, nodeID)
 	// NodeV3BillingOptOutAlreadyEnabled is acceptable on re-runs (opt-out is permanent)
 	if err != nil {
-		require.EqualError(t, err, "NodeV3BillingOptOutAlreadyEnabled")
+		// If node is already opted out, that's fine
+		require.Contains(t, err.Error(), "NodeV3BillingOptOutAlreadyEnabled")
 	}
 
 	optedOut, err := cl.IsNodeOptedOutOfV3Billing(nodeID)
 	require.NoError(t, err)
 	require.True(t, optedOut)
 }
 
+func TestSetNodeV3OptOutMetadata(t *testing.T) {
+	cl := startLocalConnection(t)
+	defer cl.Close()
+
+	identity, err := NewIdentityFromSr25519Phrase(BobMnemonics)
+	require.NoError(t, err)
+
+	farmID, twinID := assertCreateFarm(t, cl)
+	nodeID := assertCreateNode(t, cl, farmID, twinID, identity)
+
+	// Node must be opted out first
+	_, err = cl.OptOutOfV3Billing(identity, nodeID)
+	if err != nil {
+		// If node is already opted out, that's fine
+		require.Contains(t, err.Error(), "NodeV3BillingOptOutAlreadyEnabled")
+	}
+
+	metadata := []byte(`{"v4_account":"5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"}`)
+
+	_, err = cl.SetNodeV3OptOutMetadata(identity, nodeID, metadata)
+	require.NoError(t, err)
+
+	got, err := cl.GetNodeV3OptOutMetadata(nodeID)
+	require.NoError(t, err)
+	require.NotNil(t, got)
+	require.Equal(t, metadata, got)
+}
+
+func TestClearNodeV3OptOutMetadata(t *testing.T) {
+	cl := startLocalConnection(t)
+	defer cl.Close()
+
+	identity, err := NewIdentityFromSr25519Phrase(BobMnemonics)
+	require.NoError(t, err)
+
+	farmID, twinID := assertCreateFarm(t, cl)
+	nodeID := assertCreateNode(t, cl, farmID, twinID, identity)
+
+	// Node must be opted out first
+	_, err = cl.OptOutOfV3Billing(identity, nodeID)
+	if err != nil {
+		// If node is already opted out, that's fine
+		require.Contains(t, err.Error(), "NodeV3BillingOptOutAlreadyEnabled")
+	}
+
+	// Set some metadata first
+	metadata := []byte(`{"v4_account":"5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"}`)
+	_, err = cl.SetNodeV3OptOutMetadata(identity, nodeID, metadata)
+	require.NoError(t, err)
+
+	// Clear by passing empty bytes
+	_, err = cl.SetNodeV3OptOutMetadata(identity, nodeID, []byte{})
+	require.NoError(t, err)
+
+	got, err := cl.GetNodeV3OptOutMetadata(nodeID)
+	require.NoError(t, err)
+	require.Nil(t, got)
+}
+
 func TestUptimeReport(t *testing.T) {
 	cl := startLocalConnection(t)
 	defer cl.Close()

clients/tfchain-client-go/utils.go

@@ -257,6 +257,8 @@ var tfgridModuleErrors = []string{
 	"AlreadyTwinAdmin",
 	"NotTwinAdmin",
 	"TwinAdminListFull",
+	"NodeNotOptedOutOfV3Billing",
+	"NodeV3OptOutMetadataTooLong",
 }
 
 // https://github.com/threefoldtech/tfchain/blob/development/substrate-node/pallets/pallet-tft-bridge/src/lib.rs#L152

clients/tfchain-client-js/lib/node.js

@@ -154,6 +154,25 @@ async function getNodeV3BillingOptOutTimestamp (self, nodeID) {
   return result.unwrap().toNumber()
 }
 
+// getNodeV3OptOutMetadata returns the metadata stored for an opted-out node as a string,
+// or null if no metadata has been set.
+async function getNodeV3OptOutMetadata (self, nodeID) {
+  const result = await self.api.query.tfgridModule.nodeV3OptOutMetadata(nodeID)
+  if (result.isNone) return null
+  return Buffer.from(result.unwrap().toU8a(true)).toString('utf8')
+}
+
+// setNodeV3OptOutMetadata sets metadata for an opted-out node (e.g. a v4 account address).
+// The node must already be opted out of v3 billing. Pass empty string to clear.
+// Only the farm owner can call this.
+async function setNodeV3OptOutMetadata (self, nodeID, metadata, callback) {
+  const nonce = await self.api.rpc.system.accountNextIndex(self.address)
+  const bytes = Buffer.from(metadata, 'utf8')
+  return self.api.tx.tfgridModule
+    .setNodeV3OptOutMetadata(nodeID, bytes)
+    .signAndSend(self.key, { nonce }, callback)
+}
+
 async function validateNode (self, farmID) {
   const farm = await getFarm(self, farmID)
   if (farm.id !== farmID) {
@@ -171,5 +190,7 @@ module.exports = {
   optOutOfV3Billing,
   getAllowedTwinAdmins,
   isNodeOptedOutOfV3Billing,
-  getNodeV3BillingOptOutTimestamp
+  getNodeV3BillingOptOutTimestamp,
+  getNodeV3OptOutMetadata,
+  setNodeV3OptOutMetadata
 }

docs/architecture/0026-v3-node-opt-out-metadata.md

@@ -0,0 +1,168 @@
+# 26. V3 Node Opt-Out Metadata for V4 Account Linkage
+
+Date: 2026-02-26
+
+## Status
+
+Accepted
+
+## Context
+
+ADR-0025 introduced the `NodeV3BillingOptOut` mechanism allowing farmers to signal that their nodes
+are entering a migration window to Mycelium (v4). Once a node is opted out, the marketplace needs
+a way to associate that node with a v4 account so that:
+
+1. The v4 marketplace can verify the node is legitimately transitioning and not being double-billed.
+2. The v4 marketplace can attribute the node's resources and uptime to the correct farmer identity on v4.
+3. The linking is farmer-controlled, on-chain, and auditable — no off-chain oracle or manual mapping is required.
+
+### Options Considered
+
+**Option A: Hero Ledger — mutual authentication via cross-chain signed proof**
+The proposal was a **mutual authentication** scheme: a v4 account that wants to claim ownership of a v3 node
+would sign a proof using the v3 farmer private key (proving control of the v3 account), then submit
+a transaction from the v4 account to store that signed proof in Hero Ledger. Any verifier could then
+fetch the proof from KVS, retrieve the v3 farmer's public key from TFChain, and verify the signature —
+establishing that the v3 and v4 accounts are controlled by the same party without requiring a
+transaction on TFChain.
+
+Rejected because:
+
+- The chosen approach (Option D) achieves the same ownership guarantee more simply: the farmer signs a TFChain extrinsic from their v3 account, which is already the authoritative proof of ownership.
+
+**Option B: TFChain `kvstore` pallet**
+Use the existing generic key-value store pallet already deployed on TFChain. Farmers could write their v4
+account under a well-known key (e.g. `node:<node_id>:v4_account`). Rejected because the `kvstore` pallet
+is scoped per twin — any twin can write to its own namespace but there is no way to enforce that the
+writer is the farm owner of a specific node, or to enforce that the node must be opted out before the
+key can be set. The linkage would be self-asserted with no on-chain validation of the ownership
+relationship, making it unsuitable as a trust anchor for the marketplace verifier.
+
+**Option C: Extend `NodeV3BillingOptOut` map (inline struct)**
+Change the existing `NodeV3BillingOptOut` storage value type from a bare `u64` timestamp to a struct
+containing both the timestamp and optional metadata. Rejected because it requires a storage migration
+for all existing opted-out nodes, couples two distinct concerns (immutable billing state and mutable
+v4 linkage) into one storage item, and makes future independent evolution of either field harder.
+
+**Option D: Separate opt-out-gated storage map in pallet-tfgrid (chosen)**
+Add a new `NodeV3OptOutMetadata` storage map keyed by `node_id`, only writable when the node has already
+opted out. This is additive (no migration), co-located with node data, farmer-controlled, and enforces
+the invariant that metadata is only meaningful for opted-out nodes.
+
+### Per-Node vs Per-Farm Storage
+
+An alternative keying was discussed: storing one metadata entry per farm rather than per node. This would
+allow a single `set` call to link all nodes on a farm to one v4 account. Rejected in favour of per-node
+keying because:
+
+- Nodes on the same farm may migrate at different times and could legitimately map to different v4 accounts.
+- The opt-out itself (`NodeV3BillingOptOut`) is per-node, so the metadata key should match to keep the relationship unambiguous.
+
+Per-node keying is more granular, consistent with the existing opt-out model, and keeps the linkage lookup O(1) by node ID.
+
+## Decision
+
+### New Storage Item (pallet-tfgrid)
+
+```rust
+NodeV3OptOutMetadata: StorageMap<node_id (u32) → BoundedVec<u8, 256>>
+```
+
+- Keyed by node ID; presence is independent of `NodeV3BillingOptOut` at the storage level but enforced at the extrinsic level.
+- Max 256 bytes — sufficient to hold any account address format (SS58, hex, bech32) plus a small JSON envelope if needed.
+- No storage migration required; purely additive.
+
+### New Extrinsic (pallet-tfgrid)
+
+| Extrinsic | Origin | Call Index |
+| --- | --- | --- |
+| `set_node_v3_opt_out_metadata(node_id, metadata)` | Farmer (signed) | 46 |
+
+**Preconditions enforced on-chain:**
+
+1. Caller's `AccountId` maps to a twin (`TwinNotExists` otherwise).
+2. The node exists (`NodeNotExists` otherwise).
+3. The caller's twin is the farm owner twin for the node's farm (`NodeUpdateNotAuthorized` otherwise).
+4. The node is already opted out of v3 billing (`NodeNotOptedOutOfV3Billing` otherwise).
+5. `metadata.len() ≤ 256` (`NodeV3OptOutMetadataTooLong` otherwise).
+
+**Behaviour:**
+
+- If `metadata` is non-empty: upsert `NodeV3OptOutMetadata[node_id]`, emit `NodeV3OptOutMetadataUpdated { node_id, metadata: Some(metadata) }`.
+- If `metadata` is empty: remove `NodeV3OptOutMetadata[node_id]`, emit `NodeV3OptOutMetadataUpdated { node_id, metadata: None }`.
+
+The extrinsic is idempotent and can be called repeatedly to update or clear the metadata. Only the farm owner can call it, matching the ownership model of `opt_out_of_v3_billing`.
+
+### New Events (pallet-tfgrid)
+
+- `NodeV3OptOutMetadataUpdated { node_id: u32, metadata: Option<Vec<u8>> }` — emitted when metadata is set, updated, or cleared. `Some(bytes)` indicates set/update, `None` indicates clear.
+
+### New Errors (pallet-tfgrid)
+
+- `NodeNotOptedOutOfV3Billing` — returned when `set_node_v3_opt_out_metadata` is called for a node that has not yet opted out.
+- `NodeV3OptOutMetadataTooLong` — returned when the supplied metadata exceeds 256 bytes.
+
+## Flow
+
+### Full opt-out and linkage sequence
+
+```mermaid
+graph TD
+    A["Farmer"] -->|1| B["opt_out_of_v3_billing(node_id)"]
+    B --> C["Guard: caller twin == farm owner twin"]
+    C --> D["Guard: node not already opted out"]
+    D --> E["Insert: NodeV3BillingOptOut[node_id] = now()"]
+    E --> F["Emit: NodeV3BillingOptedOut { node_id, opted_out_at }"]
+    
+    A -->|2| G["set_node_v3_opt_out_metadata(node_id, v4_account_bytes)"]
+    G --> H["Guard: caller twin == farm owner twin"]
+    H --> I["Guard: NodeV3BillingOptOut[node_id] exists"]
+    I --> J["Guard: len(metadata) ≤ 256"]
+    J --> K["Insert: NodeV3OptOutMetadata[node_id] = v4_account_bytes"]
+    K --> L["Emit: NodeV3OptOutMetadataUpdated { node_id, metadata: Some( ) }"]
+```
+
+After step 2, `NodeV3OptOutMetadata[node_id]` holds the farmer's v4 account address (or any agreed-upon linking payload).
+
+### V4 Marketplace Verification Flow
+
+When a node registers or reports uptime on the v4 marketplace, the marketplace verifier must:
+
+```mermaid
+graph TD
+    A["V4 Marketplace Verifier"] -->|1| B["Query TFChain: NodeV3BillingOptOut[node_id]"]
+    B --> C{"None?"}
+    C -->|Yes| D["Node is NOT in migration window, reject"]
+    C -->|Some opted_out_at| E["Node is opted out, continue"]
+    
+    E -->|2| F["Query TFChain: NodeV3OptOutMetadata[node_id]"]
+    F --> G{"None?"}
+    G -->|Yes| H["Treat as unlinked"]
+    G -->|Some metadata| I["Decode as v4 account address"]
+    
+    I -->|3| J["Verify v4 account matches node's reported account"]
+    J --> K{"Match?"}
+    K -->|Mismatch| L["Reject; farmer must update metadata"]
+    K -->|Match| M["Node verified as legitimately transitioned"]
+    
+    M -->|4| N["Attribute node resources and uptime to verified v4 account"]
+```
+
+### Metadata Content Convention
+
+The metadata field is opaque bytes at the pallet level. A UTF-8 JSON object can be used for richer payloads, provided it stays within 256 bytes. For example:
+
+```json
+{"schema":"v1","account":"5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"}
+```
+
+The marketplace should document and enforce its expected format. The pallet enforces only the length bound.
+
+## Consequences
+
+- **No storage migration**: additive change only; existing nodes and storage layouts are unaffected.
+- **Farmer-controlled linkage**: the farm owner has sole authority to set or update the v4 account link, matching the existing ownership model.
+- **Invariant enforced on-chain**: metadata can only exist for opted-out nodes, preventing invalid or premature linking.
+- **Auditable**: all set and clear operations emit events, providing a full on-chain history of linkage changes.
+- **Marketplace trust model**: the v4 marketplace must perform two chain queries (opt-out status + metadata) to verify a node. This is a read-only operation and adds no write overhead to the critical paths.
+- **Clearing supported**: farmers can clear the metadata by passing empty bytes, which removes the storage entry entirely.