# UCAN Invocation ## Motivation Calls in RPC systems that use [UCAN][] based authorization end up mirroring delegated capabilities. This observation lead to development of [ucanto][] library which represents RPC calls as [UCAN invocation][]s. This document is an attempt to describe this invocation structure and behaviour for standardization purposes. ## Structure "Invocation" is represented by UCAN that delegates **single** capability to an "executor" _(DID holding actor with an access to private key that corresponds to a UCAN "aud")_ to excercise it. Executor MAY derive another capability and delegate to other agent or subdelegate recieved capability to other agent to perform the execution. Current version intentionally imposes "single capability" constraint so that invocations to enforce transactional semantics (either succeed or fail) with no implementation burden. :::info Note that service could still represent multiple operations via single capability if so desired. ::: In the future we are considering to remove "single capability" restriction and impose: 1. Sequential execution order. 2. Transactional semantics (succeed all or fail all). ### Execution Executors MAY receive multiple "invocations" in a single payload _(could be encoded in CAR file or embedded in a single HTTP request)_ however that SHOULD NOT imply execution order. Each invocation MUST be treated as independent of others and MAY be executed in parallel or out of order. ### Receipts :::warning ⚠️ This section is Work in progress 🚜 ::: Executors MUST issue "invocation receipts" to the issuer of the invocation signed by the executor _(private key corresponding to "aud" of the invocation)_ as proof of execution. While exact structure of the recipt is still to be determined, it is desired to capture following information: 1. **Invocation CID** - Content identifier of the invocation receipt is for. 2. **Issuer** - Issuer of the receipt that MUST be an "aud" of the invocation or it's delegate. 3. **Result** - Result of the execution. Note that some invocations MAY transition through multiple states e.g. get queued, parsed, executed etc.. Therefor **Result** could be IPLD chain of states. Executor could provide initial receipt with the prove that invocation was "queued" and later issue receipts for states as execution progresses. [ucanto]:https://github.com/web3-storage/ucanto/ [UCAN Invocation]:https://github.com/ucan-wg/spec/#28-invocation [UCAN]:https://github.com/ucan-wg/spec/