discovery-module.md 4.6 KB
Discovery Module
Table of Contents
Design
Motivation
Accessing most services requires resolving a host corresponding the public key of some service provider. This module describes the on-chain component of making this possible.
Basic Functionality
The Actors module provides a way for member accounts to stake for becoming an actor in the Joystream network, generating a new actor key along the way. This actor key then is used to fulfil the role on behalf of the member.
Due to this structure, discovering a service really means discovering which service-specific endpoint information is associated with an actor key.
The discovery workflow, then, is to retrieve some structured data by providing an actor key, and being able to verify the data has been created by the actor with the help of a cryptographic signature.
As such, the discovery workflow is and should be largely independent on how discovery is performed. The discovery workflow is almost entirely off-chain, but bootstraps from on-chain information.
The publishing workflow does require actors to understand how discovery is performed. This current version uses IPNS as a building block for discovery. The publishing workflow includes modifying on-chain data, albeit relatively rarely.
Name
Discovery
Dependencies
None.
Concepts
BootstrapEndpoints: Identifies a URL prefix for querying the discovery system.IPNSPeerId: Identifies a peer on the IPFS network, of which IPNS is part.
State
bootstrapEndpoints: A vector of bootstrap endpoints maintained by sudo.PeerIdByAccount: A map of Account IDs toIPNSPeerId. The map value also contains lifetime parameters in order to gracefully remove outdated entries.AccountInfoLifetime: A time-to-live for entries in thePeerIdByAccounttable. Configured from the genesis block.
Events
AccountInfoUpdated: A mapping from Account ID toIPNSPeerIdwas created or updated. Receiving this event allows client implementations to discard all data currently cached for the associated Account ID.
Dispatchable Methods
set_account_info_lifetime
Payload
- implied root origin
lifetime: a new lifetime value.
Description
Allow root to set the lifetime for entries in the PeerIdByAccount mapping.
Note that setting this value does not modify
the lifetime of already existing entries, and is only applied to newly
created or updated entries.
Errors
- Not root origin
- Zero or negative lifetime.
Side effect(s)
AccountInfoLifetime is updated.
Event(s)
None.
set_bootstrap_endpoints
Payload
- implied root origin
bootstrapEndpoints: a vector of URL prefixes
Description
Allow root to set the current bootstrap endpoints. Note that the number of endpoints is never expected to grow large, as new nodes are discovered from this set of bootstrap endpoints - therefore always setting the entire vector is sufficient.
Errors
- Not root origin
- Empty bootstrap endpoint vector
- Empty vector entries
Side effect(s)
bootstrapEndpoints is updated.
Event(s)
None.
set_ipns_peer_id
Payload
origin: Actor keypeerId: The IPNS peer ID.
Description
Allows actors to set their associated IPNS peer ID for discovery.
Errors
- Not actor origin
- Empty peer ID
Side effect(s)
peerIdByAccount is updated to contain the actor key as the key, and the peer
ID as the value.
Event(s)
AccountInfoUpdated
unset_ipns_peer_id
Payload
origin: Actor key
Description
Allows well-behaving actors to clear their IPNS peer ID, e.g. when shutting down.
Errors
- Not actor origin
- No error is raised if the actor is not registered; the function simply does nothing.
Side effect(s)
peerIdByAccount is updated to remove any value associated with the actor key.
Event(s)
AccountInfoUpdated
Other
Every block, outdated entries are removed and an AccountInfoUpdated event is
raised for each removed entry.