A Chain Agnostic CApability Object, or CACAO, is an IPLD representation of an object-capability.
CACAO proposes a way to leverage varsig and multidid as well as IPLD to create a common representation for various different object-capability formats, such as SIWE, SIWx, and UCAN. The IPLD representation contains common fields shared between these format. In addition this CAIP also registers varsig codes for both SIWE + ReCap and UCAN.
There has been a proliferation of ways to create object-capabilities in the web3 space. Most notably Sign-in with Ethereum, UCAN, Sign-in with X, and ReCap. All of these approaches share similar characteristics such as an issuer, audience, signature, etc. However, they are structured quite differently and have different constraints when it comes to how they are serialized and signed. Having a common representation strategy in IPLD can make it easier to interface with these various formats.
The specification consists of two main things, an IPLD schema that describes the data structure of a CACAO, and algorithms to convert SIWE(x), ReCap, and UCAN messages into and out of this data structure.
The container schema described SHOULD be encoded using the dag-cbor IPLD codec.
Important to note is that in the Abilitiy array, every NB are treated as separate. For example,
is treated as "You can post drafts to the blog, or post any status on Fridays". If you want to represent "You can post drafts to the blog on Fridays" it would need to be expressed as,
This section describes how to convert different object-capability formats into the IPLD schema described above.
The following values can be easily translated from the SIWx (CAIP-122) specification:
iss - a multidid encoded DID PKH constructued using address and chain-idaud - a multidid encoded DID based on uriv - set to versionnnc - set to nonceTimestamps
iat - is based on issued-atnbf - is based on not-beforeexp - is based on expiration-timefct.z-iat - timezone info from issued-atfct.z-nbf - timezone info from not-beforefct.z-exp - timezone info from expiration-timeSee Appendix A for the algorithm used for the conversion.
ReCap
CACAO only allows there to be one ReCap message per SIWx message.
prf - set to recap.prf, make sure that the CIDs get encoded as IPLD linksatt - set to recap.att, these should map 1-to-1Additional fields
fct.domain should be set to domainfct.statement should be set to statement (if the SIWx message contain a ReCap, the redundant data MUST be removed, e.g. recap-preamble 1*(" " recap-statement-entry "."), according to ReCap eip)fct.request-id should be set to request-idfct.resources should be set to an array containing all strings in resources except the ReCap resourceSignature
The s field is a signature encoded as a varsig and depends on which SIWx type is used. A few examples are outlined below,
SIWx, eip191:
content_multicodec - set to caip122-eip191, 0xd51emultihash - set to keccak-256, 0x1bkey_multicodec - set to secp256k1, 0xe7raw_signature - the signature bytesSIWx, solana:
According to the solana namespace,
content_multicodec - set to caip122, 0xd510multihash - set to sha2-256, 0x12key_multicodec - set to ed25519, 0xedraw_signature - the signature bytesSIWx, tezos:
According to the tezos namespace,
content_multicodec - set to caip122, 0xd510multihash - set to sha2-256, 0x12key_multicodec - set to ed25519, 0xed (or other curves based on the tezos namespace)raw_signature - the signature bytesMost fields in a UCAN should map 1-to-1 with the CACAO IPLD schema.
Additional fields
v - set to ucv from the JWT header
iss - convert the iss string of the UCAN to a multidid
aud - convert the aud string of the UCAN to a multidid
Signature
The s field is a signature encoded as a varsig and depends on which signature algorithm was used for the UCAN JWT,
content_multicodec - set to ucan-jwt, 0xd001raw_signature - the signature bytesExamples based on alg in the JWT header:
EdDSA:
multihash - set to sha2-256, 0x12key_multicodec - set to ed25519, 0xedES256K:
multihash - set to sha2-256, 0x12key_multicodec - set to secp256k1, 0xe7Other formats can be added similarly to the examples above by registering a content_multicodec for the particular object-capability.
To verify a signature of a CACAO the varsig specification is followed. Before verifying the signature the content_multicodec must be used to compute the digest used by the hash function and signature verification algorithm. Below the content_multicodec is described for 0xd510, 0xd51e, and 0xd001.
In order to verify the signature we first need to reconstruct the message that was signed. For caip122-eip191 (0xd51e) and caip122 (0xd510) we can start with the shared steps.
Reconstruct ReCap data
If present the ReCap URI and statement segment need to be reconstructed. Using the values from the CACAO reconstruct the ReCap json object (should be valid dag-json).
The recap statement segment is computed according to the ReCap eip, e.g. recap-preamble 1*(" " recap-statement-entry ".").
Reconstruct SIWx message
Start by computing values for:
address - extract address from DID PKH in cacao.isschain-id - extract chain id reference from DID PKH in cacao.issTimestamps:
issued-at - based on cacao.iat and cacao.fct.z-iatnot-before - based on cacao.nbf and cacao.fct.z-nbfexpiration-time - based on cacao.exp and cacao.fct.z-expSee Appendix A for the algorithm used for the conversion.
Finally, construct the SIWx string:
Construct signature digest, caip122 0xd510:
digest = SIWx-string
Construct signature digest, caip122-eip191 0xd51e:
Simply prepend the message according to eip191:
digest = "\x19Ethereum Signed Message:\n" + SIWx-string
0xd001)Converting a CACAO to a UCAN string that can be verified is relatively simple. Remove the s and v fields from the CACAO object and encode it as dag-json. Stringify the json object and encode using base64url. The protected header is constructed as follows,
typ - MUST equal "JWT"ucv - is set to cacao.valg - is based on key_multicodec and multihash in cacao.v:
"EdDSA" if ed25519 and sha2-256"ES256K" if secp256k1 and sha2-256Stringify the protected header json object and encode it using base64url.
digest = protected-base64url + "." + payload-base64url
For transport purposes a CACAO can be passed inside a base64url-serialized CAR file, with root of the CAR file set to a tip of capability chain. Here and now we use CARv1 format, as CARv2 is still being worked on.
We propose, that all the necessary parent CACAOs are passed there as well. This way, even if a referenced CACAO is not yet available over IPFS, both consumer and presenter of CACAO still can access it.
A common way to represent multiple different types of capabilities can enable more interoperability between object-capability systems and establishes a common ground for further innovation. CACAO relies on existing standards, such as DIDs and multicodec as a base layer for this interoperability.
Using IPLD as a represetation layer allows CACAO to easily be transfered over the internet, using IPFS or other protocols that can leverage its integrity checks.
We choose SIWx + ReCap and UCAN as examples since they represent a majority of the existing object-capabilities in use in the blockchain community today.
Present version of CACAO is a substantial change from the previous draft defined in CAIP-74.
TODO - update these examples
Below you could find a CACAO, along with its serialized presentation in CAR file.
CACAO:
CACAO Serialized: base64url-encoded CARv1 file with the IPLD block of the CACAO above:
The values in SIWx are encoded as RFC3339 strings, while CACAO requires unix timestamps (in seconds). The algorithm used to convert between the two is outlined below.
Copyright and related rights waived via CC0.