Annotations
Managing and auditing large sets of permissions can be difficult. To address this challenge, we've introduced the ability to add permission annotations to roles.
An annotation is defined by two fields:
uri- An identifier specifying the subset of permissions to be annotated. AGETrequest to this URI is expected to return an array of permissions.schema- The URL of an OpenAPI v3 schema document describing the API, including the endpoint specified inuri.
Annotations, being an auxiliary concept, are not stored in the Roles contract. Instead, they are posted to the blockchain via Poster (opens in a new tab) to become accessible to the Roles subgraph.
Resolving Annotations
The Roles app resolves annotations by fetching both the permissions to be annotated from uri and the schema document.
If the given role is not granted all of the permissions scoped by the annotation, the annotation will be ignored.
From the schema document, the Roles app extracts the Operation object (opens in a new tab) representing the uri endpoint.
This information guides the generic rendering of the annotated permission set in the app.
Example
The DeFi Kit project provides curates permission sets for common interactions with different DeFi protocols. It uses annotations to indicate which permissions belonging to a certain protocol action.
For example, a swap action of the cowswap protocol would be annotated as follows:
{
"uri": "https://kit.karpatkey.com/api/v1/permissions/eth/cowswap/swap?sell=0x6B175474E89094C44Da98b954EedeAC495271d0F&buy=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"schema": "https://kit.karpatkey.com/api/v1/openapi.json"
}The uri includes all parameters of the DeFi Kit action returns the resulting set of permissions:
The schema information allows the Roles app to render the annotated permission set in an abstracted, user friendly way:
< TODO: add Roles app screenshot showing the cowswap swap DeFi Kit action >