Variable configConst

Type declaration

• defaultsSystem: {
      clientConnectTimeoutTime: number;
      clientKeepAliveIntervalTime: number;
      clientKeepAliveTimeoutTime: number;
      nodesConnectionConnectTimeoutTime: number;
      nodesConnectionFindConcurrencyLimit: number;
      nodesConnectionHolePunchIntervalTime: number;
      nodesConnectionIdleTimeoutTime: number;
      nodesConnectionKeepAliveIntervalTime: number;
      nodesConnectionKeepAliveTimeoutTime: number;
      rpcCallTimeoutTime: number;
      rpcParserBufferSize: number;
  }

  Default system configuration. These are not meant to be changed by the user. These constants are tuned for optimal operation by the developers.

  • clientConnectTimeoutTime: number

    Timeout for the transport connecting to the client service.

    This bounds the amount of time that the client transport will wait to establish a connection to the client service of a Polykey Agent.

  • clientKeepAliveIntervalTime: number

    Interval for the keep alive of the transport connection to the client service.

    This is the minimum interval time because transport optimisations may increase the effective interval time when a keep alive message is not necessary, possibly due to other data being sent or received on the connection.

  • clientKeepAliveTimeoutTime: number

    Timeout for the keep alive of the transport connection to the client service.

    It is reset upon sending or receiving any data on the client service transport connection.

    This is the default for both sides (client and server) of the connection.

    This should always be greater than the connect timeout.

  • nodesConnectionConnectTimeoutTime: number

    Timeout for establishing a node connection.

    This applies to both normal "forward" connections and "reverse" connections started by hole punching. Reverse connections is started by signalling requests that result in hole punching.

    This is the default for both client and server sides of the connection.

    Due to transport layer implementation peculiarities, this should never be greater than the keep alive timeout.

  • nodesConnectionFindConcurrencyLimit: number

    Concurrency pool limit when finding other nodes.

    This is the parallel constant in the kademlia algorithm. It controls how many parallel connections when attempting to find a node across the network.

  • nodesConnectionHolePunchIntervalTime: number

    Interval for hole punching reverse node connections.

  • nodesConnectionIdleTimeoutTime: number

    Timeout for idle node connections.

    A node connection is idle, if nothing is using the connection. A connection is being used when its resource counter is above 0.

    The resource counter of node connections is incremented above 0 when a reference to the node connection is maintained, usually with the bracketing pattern.

    This has nothing to do with the data being sent or received on the connection. It's intended as a way of garbage collecting unused connections.

    This should always be greater than the keep alive timeout.

  • nodesConnectionKeepAliveIntervalTime: number

    Interval for the keep alive of the node connection.

    This is the minimum interval time because transport optimisations may increase the effective interval time when a keep alive message is not necessary, possibly due to other data being sent or received on the connection.

  • nodesConnectionKeepAliveTimeoutTime: number

    Timeout for the keep alive of the node connection.

    It is reset upon sending or receiving any data on the connection.

    This is the default for both sides (client and server) of the connection.

    This should always be greater than the connect timeout.

  • rpcCallTimeoutTime: number

    Timeout for each RPC stream.

    The semantics of this timeout changes depending on the context of how it is used.

    It is reset upon sending or receiving any data on the stream. This is a one-shot timer on unary calls. This repeats for every chunk of data on streaming calls.

    This is the default for both client calls and server handlers. Both the client callers and server handlers can optionally override this default.

    When the server handler receives a desired timeout from the client call, the server handler will always choose the minimum of the timeouts between the client call and server handler.

    With respect to client calls, this timeout bounds the time that the client will wait for responses from the server, as well as the time to wait for additional to be sent to the server.

    With respect to server handlers, this timeout bounds the time that the server waits to send data back to the client, as well as the time to wait for additional client data.

    Therefore it is expected that specific clients calls and server handlers will override this timeout to cater to their specific circumstances.

  • rpcParserBufferSize: number

    Buffer size of the JSON RPC parser.

    This limits the largest parseable JSON message. Any JSON RPC message greater than this byte size will be rejecte by closing the RPC stream with an error.

    This has no effect on raw streams as raw streams do not use any parser.

• defaultsUser: {
      agentServiceHost: string;
      agentServicePort: number;
      certDuration: number;
      certRenewLeadTime: number;
      clientServiceHost: string;
      clientServicePort: number;
      ipv6Only: boolean;
      nodePath: undefined | string;
      seedNodes: {};
      workers: undefined;
  }

  Default user configuration. These are meant to be changed by the user. However the defaults here provide the average user experience.

  • agentServiceHost: string

    Agent host defaults to :: dual stack. This is because the agent service is supposed to be public.

  • agentServicePort: number

  • certDuration: number

  • certRenewLeadTime: number

  • clientServiceHost: string

    Client host defaults to localhost. This will depend on the OS configuration. Usually it will be IPv4 127.0.0.1 or IPv6 ::1. This is because the client service is private most of the time.

  • clientServicePort: number

  • ipv6Only: boolean

    If using dual stack ::, then this forces only IPv6 bindings.

  • nodePath: undefined | string

  • seedNodes: {}

    Seed nodes.

    This is defaulted to {} at the object-level.

    However Polykey-CLI will use use the network to fill this.

  • workers: undefined

    Number of workers to spin up by default.

    Using undefined means all cores. Using 0 means no workers at all.

• network: {
      mainnet: Record<string, NodeAddress>;
      testnet: Record<string, NodeAddress>;
  }

  This is not used by the PolykeyAgent which defaults to {} In the future this will be replaced by mainnet.polykey.com and testnet.polykey.com. Along with the domain we will have the root public key too.

  Information that is pre-configured during distribution:

  • Domain
  • Root public key

  Information that is discovered over DNS (Authenticated DNS is optional):

  • IP address
  • Port

  As long as the root public key is provided, it is sufficient to defeat poisoning the network. The root public key should also be changed often to reduce the impact of compromises. Finally the root public key can also be signed by a third party CA providing an extra level of confidence. However this is not required.

  • mainnet: Record<string, NodeAddress>

  • testnet: Record<string, NodeAddress>

• oids: {
      extensions: {
          nodeSignature: string;
          polykeyVersion: string;
      };
  }

  Polykey OIDs These are used by the root X.509 certificates These are managed by Matrix AI and Polykey developers Starts on 1.3.6.1.4.1.57167.2 See: http://oid-info.com/get/1.3.6.1.4.1.57167

  • extensions: {
        nodeSignature: string;
        polykeyVersion: string;
    }

    • nodeSignature: string

    • polykeyVersion: string

• paths: {
      dbBase: string;
      efsBase: string;
      keysBase: string;
      stateBase: string;
      stateVersionBase: string;
      statusBase: string;
      statusLockBase: string;
      tokenBase: string;
      vaultsBase: string;
  }

  File/directory paths

  • dbBase: string

  • efsBase: string

  • keysBase: string

  • stateBase: string

  • stateVersionBase: string

  • statusBase: string

  • statusLockBase: string

  • tokenBase: string

  • vaultsBase: string

• providers: {
      github.com: {
          clientId: string;
      };
  }

  Default provider configuration These are managed by Matrix AI and Polykey developers

  • github.com: {
        clientId: string;
    }

    • clientId: string

• serviceVersion: number

  Version of the RPC and HTTP service It is only incremented on breaking changes Use this to know if you must upgrade your service client

• sourceVersion: string

  Version of source code This must match the package.json

• stateVersion: number

  Version of the state, persisted into the node state It is only incremented on breaking changes Use this to know if you have to do a schema-upgrade