Node owner contract


The Node Owner Contract is a special contract required for node to operate. It stores the node configuration and ensures that a valid deposit contract exists to hold the required amount of UTN tokens.

Note: if you are a node owner, you should NOT create the contract manually, using the documentation below. You will be provided with the proper contract generated for you. Use this documentation as a guide how to interpret the smart contract.

Contract structure

The Node Owner Contract must define several specific entities to ensure all the requirements met.

deposit_reference – UTN deposit registration

Should verify the following:

  • deposit is in UTNs (ref.state.origin == NPo4dI…);
  • deposit owner is Universa (ref.state.owner == ZNuBik…, exact address will be provided);
  • deposit is created and signed by the initial (can be switched by node owner later) private key of the node, so nobody but the node owner (that controls this private key) could create the deposit and register the node owner contract;
  • deposit contract has reference to node owner contract in its transactional.data (prevents multiple usage of the same deposit contract)
  • deposit amount matches the requirements
    name: deposit_reference
    where:
      all_of:
      - ref.state.origin == NPo4dIkNdgYfGiNrdExoX003+lFT/d45OA6GifmcRoTzxSRSm5c5jDHBSTaAS+QleuN7ttX1rTvSQbHIIqkcK/zWjx/fCpP9ziwsgXbyyCtUhLqP9G4YZ+zEY/yL/GVE
      - ref.state.owner == ZNuBik…
      - ref.state.creator == JiYtcn…
      - ref.state.data.amount == '1000000'
      - ref.transactional.data.node_owner_contract_id==this.origin

state.data – node configuration parameters

state:
  data:
    public_key: HggcAQ...
    node_name: node1
    node_number: 1
    owner_email: [email protected]
    public_host: node1.universa.io
    ip:
    - 192.168.1.1
    node_active: true
    http_server_port: 2082
    http_client_port: 8080
    udp_server_port: 6001

ModifyDataPermissions – to update the node configuration

The fields are divided into three groups:

  • Sensitive network configuration. Can be updated by Universa admin only:
    • node_number
    • public_host
    • node_active
  • Node owner contact information. Can be updated by the node owner only:
    • owner_email
  • Non-sensitive node configuration (messing with that will not disrupt network operation). Can be updated by either node owner or admin:
    • public_key
    • http_server_port
    • ip
    • node_name
    • http_client_port
    • udp_server_port

Owner of the contract

The owner of the contract is ListRole. It includes all the owner roles of UTN contracts that were used to form single UTN deposit contract. ListRole mode is QUORUM of 3/4. Please note that every role in the list has equal 'rights' comparing to others regardless of the amount of UTNs in corresponding deposit part.

Keeping node owning fair is up to its owner. The easiest way to keep it fair is follow the recommendations below:

  • splitting investments into several parts of equal size so they count as several 'votes' in ListRole;
  • sign and register deposit contract and node owner contract with single transaction to ensure that owner contract owner is corresponding to deposit.

Contract processing flow

Startup

  • When the node starts for the very first time, it receives the list of pre-registered node owner contracts. It then stores the list in its database.
  • During startup, the node checks the owner contracts in its database and converts the contracts into the network configuration: node numbers, hosts, ports, keys etc.
  • The node looks for its configuration (the one that has a public key matching the private key of the node). Node doesn’t launch if the configuration is missing.
  • The node launches and checks the status of every node owner contract on the network (forced synchronisation).
  • If the contract is not APPROVED, the node tries to get the latest revision from any other random node. After getting the new revision, the node repeats the verification.
  • If an approved contract isn’t found at all, the corresponding node is removed from the list. The node will shutdown if such a contract belongs to itself.
  • After all contracts have been checked, the node becomes operational and can receive the client requests.

Running

  • Every registered contract is being validated (as a low-priority task) for being the correct node owner contract.
  • Ones that passed the check, are processed by the node in one of two possible ways:
    • for root contracts, the new nodes are added to network configuration;
    • for new revisions, the information regarding the corresponding nodes is updated in the network configuration.

If, during processing a new revision, the new information belongs to this node itself, the behaviour will depend on fields changed:

  • node_number – restart;
  • node_name – restart;
  • public_key – shutdown (manual restart);
  • http_client_port – restart;
  • http_server_port – restart;
  • udp_server_port – restart;
  • public_host – no actions;
  • ip – no actions;
  • node_active – shutdown (node become inactive);
  • owner_email – no actions.