feat: Add V3 billing opt-out and twin admin management to Go client

Implement client methods for V3 billing opt-out functionality including OptOutOfV3Billing, AddTwinAdmin, RemoveTwinAdmin, GetAllowedTwinAdmins, and IsNodeOptedOutOfV3Billing. Add corresponding event types NodeV3BillingOptedOut, TwinAdminAdded, and TwinAdminRemoved. Include comprehensive unit tests and update error definitions for new tfgrid and smart contract module errors.

Author: sameh-farouk

clients/tfchain-client-go/events.go

@@ -331,6 +331,25 @@ type ZosVersionUpdated struct {
 	Topics  []types.Hash
 }
 
+type NodeV3BillingOptedOut struct {
+	Phase      types.Phase
+	NodeID     types.U32 `json:"node_id"`
+	OptedOutAt types.U64 `json:"opted_out_at"`
+	Topics     []types.Hash
+}
+
+type TwinAdminAdded struct {
+	Phase   types.Phase
+	Account AccountID `json:"account_id"`
+	Topics  []types.Hash
+}
+
+type TwinAdminRemoved struct {
+	Phase   types.Phase
+	Account AccountID `json:"account_id"`
+	Topics  []types.Hash
+}
+
 type EventSchedulerCallUnavailable struct {
 	Phase  types.Phase
 	Task   types.TaskAddress
@@ -467,6 +486,9 @@ type EventRecords struct {
 	TfgridModule_FarmingPolicySet              []FarmingPolicySet              //nolint:stylecheck,golint
 	TfgridModule_FarmCertificationSet          []FarmCertificationSet          //nolint:stylecheck,golint
 	TfgridModule_ZosVersionUpdated             []ZosVersionUpdated             //nolint:stylecheck,golint
+	TfgridModule_NodeV3BillingOptedOut         []NodeV3BillingOptedOut         //nolint:stylecheck,golint
+	TfgridModule_TwinAdminAdded                []TwinAdminAdded                //nolint:stylecheck,golint
+	TfgridModule_TwinAdminRemoved              []TwinAdminRemoved              //nolint:stylecheck,golint
 
 	// burn module events
 	BurningModule_BurnTransactionCreated []BurnTransactionCreated //nolint:stylecheck,golint

clients/tfchain-client-go/node.go

@@ -805,6 +805,124 @@ func (s *Substrate) GetDedicatedNodePrice(nodeID uint32) (uint64, error) {
 	return uint64(price), nil
 }
 
+// OptOutOfV3Billing opts a node out of the v3 billing system, opening a free migration window.
+// Only the farmer who owns the node can call this.
+func (s *Substrate) OptOutOfV3Billing(identity Identity, nodeID uint32) (hash types.Hash, err error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return hash, err
+	}
+
+	c, err := types.NewCall(meta, "TfgridModule.opt_out_of_v3_billing", nodeID)
+	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 opt out of v3 billing")
+	}
+
+	return callResponse.Hash, nil
+}
+
+// AddTwinAdmin adds an account to the list of twin admins allowed to deploy on opted-out nodes.
+// Requires council (restricted) origin.
+func (s *Substrate) AddTwinAdmin(identity Identity, account AccountID) (hash types.Hash, err error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return hash, err
+	}
+
+	c, err := types.NewCall(meta, "TfgridModule.add_twin_admin", account)
+	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 add twin admin")
+	}
+
+	return callResponse.Hash, nil
+}
+
+// RemoveTwinAdmin removes an account from the list of twin admins allowed to deploy on opted-out nodes.
+// Requires council (restricted) origin.
+func (s *Substrate) RemoveTwinAdmin(identity Identity, account AccountID) (hash types.Hash, err error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return hash, err
+	}
+
+	c, err := types.NewCall(meta, "TfgridModule.remove_twin_admin", account)
+	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 remove twin admin")
+	}
+
+	return callResponse.Hash, nil
+}
+
+// GetAllowedTwinAdmins returns the list of accounts allowed to deploy on opted-out nodes.
+// Returns an empty slice if no admins have been configured.
+func (s *Substrate) GetAllowedTwinAdmins() ([]AccountID, error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return nil, err
+	}
+
+	key, err := types.CreateStorageKey(meta, "TfgridModule", "AllowedTwinAdmins")
+	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 allowed twin admins")
+	}
+
+	if len(*raw) == 0 {
+		return []AccountID{}, nil
+	}
+
+	var admins []AccountID
+	if err := Decode(*raw, &admins); err != nil {
+		return nil, errors.Wrap(err, "failed to decode allowed twin admins")
+	}
+
+	return admins, nil
+}
+
+// IsNodeOptedOutOfV3Billing returns true if the node has opted out of v3 billing.
+func (s *Substrate) IsNodeOptedOutOfV3Billing(nodeID uint32) (bool, error) {
+	cl, meta, err := s.GetClient()
+	if err != nil {
+		return false, err
+	}
+
+	bytes, err := Encode(nodeID)
+	if err != nil {
+		return false, errors.Wrap(err, "substrate: encoding error building query arguments")
+	}
+
+	key, err := types.CreateStorageKey(meta, "TfgridModule", "NodeV3BillingOptOut", bytes)
+	if err != nil {
+		return false, errors.Wrap(err, "failed to create substrate query key")
+	}
+
+	raw, err := cl.RPC.State.GetStorageRawLatest(key)
+	if err != nil {
+		return false, errors.Wrap(err, "failed to lookup node v3 billing opt-out")
+	}
+
+	return len(*raw) > 0, 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

@@ -67,6 +67,54 @@ func TestSetDedicatedNodePrice(t *testing.T) {
 	require.Equal(t, uint64(price), priceSet)
 }
 
+func TestOptOutOfV3Billing(t *testing.T) {
+	cl := startLocalConnection(t)
+	defer cl.Close()
+
+	// Bob is the farmer
+	identity, err := NewIdentityFromSr25519Phrase(BobMnemonics)
+	require.NoError(t, err)
+
+	farmID, twinID := assertCreateFarm(t, cl)
+	nodeID := assertCreateNode(t, cl, farmID, twinID, identity)
+
+	_, err = cl.OptOutOfV3Billing(identity, nodeID)
+	// NodeV3BillingOptOutAlreadyEnabled is acceptable on re-runs (opt-out is permanent)
+	if err != nil {
+		require.EqualError(t, err, "NodeV3BillingOptOutAlreadyEnabled")
+	}
+
+	optedOut, err := cl.IsNodeOptedOutOfV3Billing(nodeID)
+	require.NoError(t, err)
+	require.True(t, optedOut)
+}
+
+func TestGetAllowedTwinAdmins(t *testing.T) {
+	cl := startLocalConnection(t)
+	defer cl.Close()
+
+	rootIdentity, err := NewIdentityFromSr25519Phrase(AliceMnemonics)
+	require.NoError(t, err)
+
+	bobAccount, err := FromAddress(BobAddress)
+	require.NoError(t, err)
+
+	// Ensure Bob is in the list
+	_, err = cl.AddTwinAdmin(rootIdentity, bobAccount)
+	require.NoError(t, err)
+	admins, err := cl.GetAllowedTwinAdmins()
+	require.NoError(t, err)
+	require.Contains(t, admins, bobAccount)
+
+	// Clean up
+	_, err = cl.RemoveTwinAdmin(rootIdentity, bobAccount)
+	require.NoError(t, err)
+
+	admins, err = cl.GetAllowedTwinAdmins()
+	require.NoError(t, err)
+	require.NotContains(t, admins, bobAccount)
+}
+
 func TestUptimeReport(t *testing.T) {
 	cl := startLocalConnection(t)
 	defer cl.Close()

clients/tfchain-client-go/utils.go

@@ -129,6 +129,7 @@ var smartContractModuleErrors = []string{
 	"UnauthorizedToSetExtraFee",
 	"RewardDistributionError",
 	"ContractPaymentStateNotExists",
+	"OnlyTwinAdminCanDeployOnThisNode",
 }
 
 // https://github.com/threefoldtech/tfchain/blob/development/substrate-node/pallets/pallet-tfgrid/src/lib.rs#L442
@@ -249,6 +250,12 @@ var tfgridModuleErrors = []string{
 	"InvalidRelayAddress",
 	"InvalidTimestampHint",
 	"InvalidStorageInput",
+	"TwinTransferRequestNotFound",
+	"TwinTransferNewAccountHasTwin",
+	"TwinTransferPendingExists",
+	"NodeV3BillingOptOutAlreadyEnabled",
+	"AlreadyTwinAdmin",
+	"NotTwinAdmin",
 }
 
 // https://github.com/threefoldtech/tfchain/blob/development/substrate-node/pallets/pallet-tft-bridge/src/lib.rs#L152