github.com/nspcc-dev/neo-go@v0.105.2-0.20240517133400-6be757af3eba/pkg/rpcclient/rolemgmt/roles.go (about)

     1  /*
     2  Package rolemgmt allows to work with the native RoleManagement contract via RPC.
     3  
     4  Safe methods are encapsulated into ContractReader structure while Contract provides
     5  various methods to perform the only RoleManagement state-changing call.
     6  */
     7  package rolemgmt
     8  
     9  import (
    10  	"github.com/nspcc-dev/neo-go/pkg/core/native/nativehashes"
    11  	"github.com/nspcc-dev/neo-go/pkg/core/native/noderoles"
    12  	"github.com/nspcc-dev/neo-go/pkg/core/transaction"
    13  	"github.com/nspcc-dev/neo-go/pkg/crypto/keys"
    14  	"github.com/nspcc-dev/neo-go/pkg/neorpc/result"
    15  	"github.com/nspcc-dev/neo-go/pkg/rpcclient/unwrap"
    16  	"github.com/nspcc-dev/neo-go/pkg/util"
    17  )
    18  
    19  // Invoker is used by ContractReader to call various methods.
    20  type Invoker interface {
    21  	Call(contract util.Uint160, operation string, params ...any) (*result.Invoke, error)
    22  }
    23  
    24  // Actor is used by Contract to create and send transactions.
    25  type Actor interface {
    26  	Invoker
    27  
    28  	MakeCall(contract util.Uint160, method string, params ...any) (*transaction.Transaction, error)
    29  	MakeUnsignedCall(contract util.Uint160, method string, attrs []transaction.Attribute, params ...any) (*transaction.Transaction, error)
    30  	SendCall(contract util.Uint160, method string, params ...any) (util.Uint256, uint32, error)
    31  }
    32  
    33  // Hash stores the hash of the native RoleManagement contract.
    34  var Hash = nativehashes.RoleManagement
    35  
    36  const designateMethod = "designateAsRole"
    37  
    38  // ContractReader provides an interface to call read-only RoleManagement
    39  // contract's methods.
    40  type ContractReader struct {
    41  	invoker Invoker
    42  }
    43  
    44  // Contract represents a RoleManagement contract client that can be used to
    45  // invoke all of its methods.
    46  type Contract struct {
    47  	ContractReader
    48  
    49  	actor Actor
    50  }
    51  
    52  // DesignationEvent represents an event emitted by RoleManagement contract when
    53  // a new role designation is done.
    54  type DesignationEvent struct {
    55  	Role       noderoles.Role
    56  	BlockIndex uint32
    57  }
    58  
    59  // NewReader creates an instance of ContractReader that can be used to read
    60  // data from the contract.
    61  func NewReader(invoker Invoker) *ContractReader {
    62  	return &ContractReader{invoker}
    63  }
    64  
    65  // New creates an instance of Contract to perform actions using
    66  // the given Actor. Notice that RoleManagement's state can be changed
    67  // only by the network's committee, so the Actor provided must be a committee
    68  // actor for designation methods to work properly.
    69  func New(actor Actor) *Contract {
    70  	return &Contract{*NewReader(actor), actor}
    71  }
    72  
    73  // GetDesignatedByRole returns the list of the keys designated to serve for the
    74  // given role at the given height. The list can be empty if no keys are
    75  // configured for this role/height.
    76  func (c *ContractReader) GetDesignatedByRole(role noderoles.Role, index uint32) (keys.PublicKeys, error) {
    77  	return unwrap.ArrayOfPublicKeys(c.invoker.Call(Hash, "getDesignatedByRole", int64(role), index))
    78  }
    79  
    80  // DesignateAsRole creates and sends a transaction that sets the keys used for
    81  // the given node role. The action is successful when transaction ends in HALT
    82  // state. The returned values are transaction hash, its ValidUntilBlock value
    83  // and an error if any.
    84  func (c *Contract) DesignateAsRole(role noderoles.Role, pubs keys.PublicKeys) (util.Uint256, uint32, error) {
    85  	return c.actor.SendCall(Hash, designateMethod, int(role), pubs)
    86  }
    87  
    88  // DesignateAsRoleTransaction creates a transaction that sets the keys for the
    89  // given node role. This transaction is signed, but not sent to the network,
    90  // instead it's returned to the caller.
    91  func (c *Contract) DesignateAsRoleTransaction(role noderoles.Role, pubs keys.PublicKeys) (*transaction.Transaction, error) {
    92  	return c.actor.MakeCall(Hash, designateMethod, int(role), pubs)
    93  }
    94  
    95  // DesignateAsRoleUnsigned creates a transaction that sets the keys for the
    96  // given node role. This transaction is not signed and just returned to the
    97  // caller.
    98  func (c *Contract) DesignateAsRoleUnsigned(role noderoles.Role, pubs keys.PublicKeys) (*transaction.Transaction, error) {
    99  	return c.actor.MakeUnsignedCall(Hash, designateMethod, nil, int(role), pubs)
   100  }