Control Planes
Last updated
Was this helpful?
Last updated
Was this helpful?
Control Planes are a primary way for consumers to interact with a LearnCard. A Control Plane provides an abstraction for a higher-order wallet object to initiate complex workflows while being agnostic to the means of accomplishing the workflow.
Align plugins based on primary action categories: Identity, Signing, Verification, Storage, Caching, and Communication.
Specify interfaces for conforming plugins to implement.
Provide execution environments that support more complex workflows.
Allows for utilizing multiple plugins to support a particular request.
Streamline functionality for high-quality UX requirements, such as caching and querying capabilities.
Incentivizes plugin convergence, rather than divergence.
Enables plugin discovery, both internal and external.
Each control plane serves a specific purpose:
ID
Identity management
did, keypair
Read
Resolving URIs to credentials
get
Store
Storing credentials
upload, uploadEncrypted, uploadMany
Index
Managing credential references
get, add, update, remove
Cache
Caching for performance
getIndex, setIndex, getVc, setVc
Context
Managing contextual information
resolveDocument
A key feature of the control planes system is that when appropriate, a specific plugin implementing a plane can be chosen. For example, when storing a credential, you can specify which storage plugin to use:
To help better understand what Control Planes are, it may be easiest for you to take a look at the available Control Planes within LearnCard:
The ID Control Plane is the interface responsible for managing the holder's identity. This means storing/managing key material.
Plugins that implement this Control Plane will generally need to be instantiated in some way, and with some kind of input, such as a seed/existing key material, or by making a request to a third party that can provide key material.
The ID Plane implements two methods: did, and keypair
The Read Plane implements one method: get
If a plugin implementing get is unable to resolve a URI, it should return undefined, allowing other plugins to take a crack at resolving that URI. If no plugins are able to resolve the URI, the LearnCard will return undefined.
The Store Plane implements three methods: upload, (optionally) uploadEncrypted, and (optionally) uploadMany
The uploadEncrypted method allows you to encrypt a credential before uploading it, optionally specifying recipients who are allowed to decrypt the resolved credential. This is generally going to be safer, and it is heavily encouraged for Providers to implement this method!
The Index Plane implements eight methods: get, (optionally) getPage, (optionally) getCount, add, addMany, update, remove, and removeAll.
When there are a lot of credentials stored in the index for a given query, it can be useful to paginate your queries rather than request all of them at once. That is what getPage is for! This call will return an object of the following shape:
Using the hasMore and cursor fields, you can determine if you should request the next page, as well as how to request the next page. The below example shows a simple way to request all available pages:
Sometimes, it can be useful for an app to display the total number of records for a given query without wanting to actual grab every credential for that query. This is where getCount comes in handy!
The add method takes in a CredentialRecord and adds it to the holder's personal index.
The optional addMany method takes in an array of CredentialRecords and adds them to the holder's personal index.
The update method takes in an ID and an update object and updates a CredentialRecord in the holder's personal index.
The remove method takes in an ID and removes the CredentialRecord with the corresponding ID from the holder's personal index.
The optional removeAll method flushes all CredentialRecords from the holder's personal index.
The Cache Control Plane is responsible for speeding up and making a LearnCard more efficient through the use of Caching.
To better encourage and allow separation of the caching between different planes, Cache plugins are required to implement separate caching methods for each plane. In general, when consuming a LearnCard object, you should rarely, if ever, need to interact with the cache directly—it should just work underneath each of the other Planes 🚀!
The Cache Plane implements ten methods: getIndex, setIndex, getIndexPage, setIndexPage, (optionally) getIndexCount, (optionally) setIndexCount, flushIndex, getVc, setVc, and flushVc
The getIndex method takes in a query returns a list of CredentialRecords, similar to the Index Plane's get method.
The setIndex method takes in a query and a list of CredentialRecords and caches the records against the query, returning true if successful and false if not.
The getIndexPage method takes in a query with pagination options and returns a paginated result of CredentialRecords, similar to the Index Plane's getPage method.
The setIndexPage method takes in a query with pagination options and a paginated result of CredentialRecords and caches the result against the query/options, returning true if successful and false if not.
The getIndexCount method takes in a query and returns a number, intending to cache the Index Plane's getCount method.
The setIndexCount method takes in a query and number and caches the number against the query, returning true if successful and false if not.
The flushIndex method empties out everything in the cache that can be returned by getIndex, getIndexPage, or getIndexCount
The getVc method takes in a URI and returns a Verifiable Credential, similar to the Read Plane's get method.
The setVc method takes in a URI and a Verifiable Credential and caches the Verifiable Credential against the URI, returning true if successful and false if not.
The flushVc method empties out everything in the cache that can be returned by getVc.
The Context Control Plane allows plugins to control how these JSON-LD contexts get resolved. Because it should be considered a security hole to resolve a context at runtime, plugins are expected to expose two different methods for static and dynamic resolution. On the final resulting LearnCard object, there is then only one method with an argument allowing for contexts to be resolved dynamically.
The Context Plane implements one method: resolveDocument
The resolveDocument method takes in the URI to a JSON-LD Context and returns the full JSON-LD Context. By passing in true as the second argument, contexts may be resolved dynamically.
When creating a Plugin that implements the Context Plane, you must implement the resolveStaticDocument method. This method simply does the same as the LearnCard-level resolveDocument method, but does not allow passing in a second argument to denote resolving dynamically.
When creating a Plugin that implements the Context Plane, you may implement the resolveRemoteDocument method. This method is identical to resolveStaticDocument, but by using this method, you are signifying that contexts will be loaded dynamically.
The did method (optionally) takes in a , and returns a did.
The keypair method (optionally) takes in a cryptographic algorithm (e.g. ed25519, secp256k1, etc), and returns a .
The Read Control Plane is the interface responsible for resolving a to its Verifiable Credential.
If the LearnCard also implements the , then this Plane will automatically be cached!
The get method takes in a and resolves it to a Verifiable Credential.
The getMany method takes in an array of s and resolves them to an array of Verifiable Credentials.
The Store Control Plane is the interface responsible for storing a Verifiable Credential and returning a that resolves to it.
If the LearnCard also implements the , then this Plane will automatically be cached!
The upload method takes in a Verifiable Credential, stores the credential, and converts it into a resolvable .
The uploadMany method takes in an array of Verifiable Credentials, stores the credentials, and converts them into an array of resolvable .
The Index Control Plane is the interface responsible for managing operations on the holder's personal index.
If the LearnCard also implements the , then this method will automatically be cached!
The get method takes in a Mongo-style query and returns a list of CredentialRecords, which are primarily an ID, a , and some metadata.
If the LearnCard also implements the , then this method will automatically be cached!
If the LearnCard also implements the , then this Plane will automatically be cached!
When working with , such as with , you'll often need to resolve contexts. These contexts are themselves JSON-LD documents, being hosted at the URL embedded in the JSON-LD object. While it is easy enough to make a simple request to that URL and retrieve that document, there are many reasons why you might not want to do that every time. Most notably, for security and performance.
Resolving JSON-LD contexts dynamically comes with some serious security implications. Please read the following for more detail: