30:T357b,intro = Syntax.md`# UCAN Invocation Specification v0.1.0 ## Editors - [Brooklyn Zelenka](https://github.com/expede/), [Fission](https://fission.codes/) - [Irakli Gozalishvili](https://github.com/Gozala), [Protocol Labs](http://protocol.ai) ## Authors - [Brooklyn Zelenka](https://github.com/expede/), [Fission](https://fission.codes/) - [Irakli Gozalishvili](https://github.com/Gozala), [Protocol Labs](http://protocol.ai) ## Depends On - [DAG-CBOR] - [UCAN] - [UCAN-IPLD] - [Varsig] # 0 Abstract UCAN Invocation defines a format for expressing the intention to execute delegated UCAN capabilities, the attested receipts from an execution, and how to extend computation via promise pipelining. ## Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). # 1 Introduction > Just because you can doesn't mean that you should > > — Anonymous UCAN is a chained-capability format. A UCAN contains all of the information that one would need to perform some task, and the provable authority to do so. This begs the question: can UCAN be used directly as an RPC language? Some teams have had success with UCAN directly for RPC when the intention is clear from context. This can be successful when there is more information on the channel than the UCAN itself (such as an HTTP path that a UCAN is sent to). However, capability invocation contains strictly more information than delegation: all of the authority of UCAN, plus the command to perform the task. ## 1.1 Intuition ## 1.1.1 Car Keys Consider the following fictitious scenario: Akiko is going away for the weekend. Her good friend Boris is going to borrow her car while she's away. They meet at a nearby cafe, and Akiko hands Boris her car keys. Boris now has the capability to drive Akiko's car whenever he wants to. Depending on their plans for the rest of the day, Akiko may find Boris quite rude if he immediately leaves the cafe to go for a drive. On the other hand, if Akiko asks Boris to run some last minute pre-vacation errands for that require a car, she may expect Boris to immediately drive off. ## 1.1.2 Lazy vs Eager Evaluation In a referentially transparent setting, the description of a task is equivalent to having done so: a function and its results are interchangeable. [Programming languages with call-by-need semantics](https://en.wikipedia.org/wiki/Haskell) have shown that this can be an elegant programming model, especially for pure functions. However, _when_ something will run can sometimes be unclear. Most languages use eager evaluation. Eager languages must contend directly with the distinction between a reference to a function and a command to run it. For instance, in JavaScript, adding parentheses to a function will run it. Omitting them lets the program pass around a reference to the function without immediately invoking it. ~~~js const message = () => alert("hello world") message // Nothing happens message() // A message interups the user ~~~ Delegating a capability is like the statement \`message\`. Task is akin to \`message()\`. It's true that sometimes we know to run things from their surrounding context without the parentheses: ~~~js [1, 2, 3].map(message) // Message runs 3 times ~~~ However, there is clearly a distinction between passing a function and invoking it. The same is true for capabilities: delegating the authority to do something is not the same as asking for it to be done immediately, even if sometimes it's clear from context. ## 1.2 Gossiping of delegations In web3.storage user \`alice@web.mail\` can delegate to store file in her space to \`bob@send.io\` by sending that delegation to \`web3.storage\`. If service were to interpret this as invocation it would fail due to principal misalignment. By distinguishing capability invocation from delegation service is able to more correctly handle such a message, if it is an invocation it will still error due to principal misalignment, if it is a delegation it will hold it in Bob's inbox to be picked up when he's comes online. ## 1.3 Separation of Concerns Information about the scheduling, order, and pipelining of tasks is orthogonal to the flow of authority. An agent collaborating with the original executor does not need to know that their call is 3 invocations deep; they only need to know that they been asked to perform some task by the latest invoker. As we shall see in the [discussion of promise pipelining][pipelines], asking an agent to perform a sequence of tasks before you know the exact parameters requires delegating capabilities for all possible steps in the pipeline. Pulling pipelining detail out of the core UCAN spec serves two functions: it keeps the UCAN spec focused on the flow of authority, and makes salient the level of de facto authority that the executor has (since they can claim any value as having returned for any step). ~~~ ────────────────────────────────────────────Time──────────────────────────────────────────────────────► ┌──────────────────────────────────────────Delegation─────────────────────────────────────────────────────┐ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ Alice ├──►│ Bob ├──►│ Carol ├────────►│ Dan ├───────────────►│ Erin │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────Invocation─────────────────────────────────────────────────────┐ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ │ │ │ │ │ │ Carol ╞═══All══►│ Dan │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ │ │ │ │ │ │ Dan ╞═══════════Update DB═════════►│ Erin │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ │ │ │ │ │ │ Dan ╞═══Read Email══►│ Erin │ │ │ │ │ ▲ │ │ │ │ └─────────┘ ┆ └─────────┘ │ │ With │ │ Result │ │ ┌─────────┐ Of ┌─────────┐ │ │ │ │ ┆ │ │ │ │ │ Dan ╞════Set DNS══►│ Erin │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ~~~ ## 1.3 A Note On Serialization The JSON examples below are given in [DAG-JSON], but UCAN Task is actually defined as IPLD. This makes UCAN Task agnostic to encoding. DAG-JSON follows particular conventions around wrapping CIDs and binary data in tags like so: ### CID ~~~json {"/": "Qmf412jQZiuVUtdgnB36FXFX7xg5V6KEbSJ4dpQuhkLyfD"} ~~~ ### Bytes ~~~json {"/": {"bytes": "s0m3Byte5"}} ~~~ This format help disambiguate type information in generic [DAG-JSON] tooling. However, your presentation need not be in this specific format, as long as it can be converted to and from this cleanly. As it is used for the signature format, [DAG-CBOR] is RECOMMENDED. ## 1.4 Signatures All payloads described in this spec MUST be signed with a [Varsig]. ### 2.2.1 Task A [Task] is like a deferred function application: a request to perform some action on a resource with specific input. ### 2.2.2 Authorization An [Authorization] is a cryptographically signed proof permitting execution of referenced tasks. It allows invoker to authorize a group of tasks using one cryptographic signature. ### 2.2.3 Invocation An [Invocation] is an invoker authorized instruction to the [Executor] to run the [Task]. ### 2.2.4 Result A [Result] is the output of a [Task]. ### 2.2.5 Receipt A [Receipt] is a cryptographically signed description of the [Invocation] output. ### 2.2.6 Effect An [Effect] are the instruction to the [Executor] to run set of [Task]s concurrently. ## 2.3 IPLD Schema # 2 High-Level Concepts ## 2.1 Roles Task adds two new roles to UCAN: invoker and executor. The existing UCAN delegator and delegate principals MUST persist to the invocation. | UCAN Field | Delegation | Task | | ---------- | -------------------------------------- | ------------------------------- | | \`iss\` | Delegator: transfer authority (active) | Invoker: request task (active) | | \`aud\` | Delegate: gain authority (passive) | Executor: perform task (active) | ### 2.1.1 Invoker The invoker signals to the executor that a task associated with a UCAN SHOULD be performed. The invoker MUST be the UCAN delegator. Their DID MUST be authenticated in the \`iss\` field of the contained UCAN. ### 2.1.2 Executor The executor is directed to perform some task described in the UCAN by the invoker. The executor MUST be the UCAN delegate. Their DID MUST be set the in \`aud\` field of the contained UCAN. ## 2.2 Components ${LINKS} `31:T67f,schema = Syntax.ipldsch` type Task struct { on URI call Ability input {String: Any} nnc string } type URI string type Ability string type Authorization struct { # Authorization is denoted by the set of links been authorized scope [&Any] # Scope signed by the invoker s VarSig } type Invocation struct { v SemVer run &Task # Receipt of the invocation that caused this invocation cause optional &Receipt # Task authorization. auth &Authorization meta {String : any} prf [&UCAN] } type SemVer string type Receipt struct { # Invocation this is a receipt for ran &Invocation # Output of the invocation out Result # Effects to be performed fx Effect # All the other metadata meta {String: any} # Principal that issued this receipt. If omitted issuer is # inferred from the invocation task audience. iss optional Principal # When issuer is different from executor this MUST hold a UCAN # delegation chain from executor to the issuer. Should be omitted when # executor is an issuer. prf [&UCAN] # Signature from the "iss". s Varsig } type Result union { | any "ok" # Success | any "error" # Error } representation kinded # Represents a request to invoke enclosed set of tasks concurrently type Effect struct { # Primary set of tasks to be invoked fork [&Task] # Continuation for straight-line programs join optional &Task } # Way to reference result of the Task type Await union { | &Task "await/*" | &Task "await/ok" | &Task "await/error" } representation keyed `32:T8c3,taskField = Syntax.md` ## 3.1 Schema ${schema.Task.source} ## 3.2 Fields ### 3.2.1 Resource The \`on\` field MUST contain the [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) of the resource being accessed. If the resource being accessed is some static data, it is RECOMMENDED to reference it by the [\`data\`](https://en.wikipedia.org/wiki/Data_URI_scheme), [\`ipfs\`](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#native-urls), or [\`magnet\`](https://en.wikipedia.org/wiki/Magnet_URI_scheme) URI schemes. ### 3.2.3 Ability The \`call\` field MUST contain a [UCAN Ability](https://github.com/ucan-wg/spec/#23-ability). This field can be thought of as the message or trait being sent to the resource. ### 3.2.4 Input The OPTIONAL \`input\` field, MAY contain any parameters expected by the URI/Ability pair, which MAY be different between different URIs and Abilities, and is thus left to the executor to define the shape of this data. If present, \`input\` field MUST have an IPLD [map representation][ipld representation], and thus MAY be a: 1. [struct](https://ipld.io/docs/schemas/features/representation-strategies/#struct-map-representation) in map representation. 2. [keyed](https://ipld.io/docs/schemas/features/representation-strategies/#union-keyed-representation), [enveloped](https://ipld.io/docs/schemas/features/representation-strategies/#union-envelope-representation) or [inline](https://ipld.io/docs/schemas/features/representation-strategies/#union-inline-representation) union. 3. [unit](https://github.com/ipld/ipld/blob/353baf885adebb93191cbe1f7be34f0517e20bbd/specs/schemas/schema-schema.ipldsch#L753-L789) in empty map representation. 4. [map](https://ipld.io/docs/schemas/features/representation-strategies/#map-map-representation) in map representation. UCAN capabilities provided in [Proofs] MAY impose certain constraint on the type of \`input\` allowed. If \`input\` field is not present, it is implicitly a \`unit\` represented as empty map. ### 3.2.6 Nonce If present, the OPTIONAL \`nnc\` field MUST include a random nonce expressed in ASCII. This field ensures that multiple invocations are unique. ## 3.3 DAG-JSON Examples ### 3.3.1 Interacting with an HTTP API ${LINKS}`33:T8a6,invocationIntro = Syntax.md` # 5 Invocation As [noted in the introduction][lazy-vs-eager], there is a difference between a reference to a function and calling that function. The [Invocation] is an instruction to the [Executor] to perform enclosed [Task]. [Invocation]s are not executable until they have been provided provable authority (in form of UCANs in the \`prf\` field) and an [Authorization] (in the \`auth\` field) from the [Invoker]. If \`auth\` field MUST be set to the [Authorization] (link) which contains \`run\` in it's scope field. The Invocation of the [Task] with an [Authorization] which does not includes [Task] in the \`scope\` MUST be considered invalid. ## 5.1 Schema ${schema.Invocation.source} ## 5.2 Fields ### 5.2.1 UCAN Task Version The \`v\` field MUST contain the SemVer-formatted version of the UCAN Invocation Specification that this struct conforms to. ### 5.2.2 Task The \`run\` field MUST contain a link to the [Task] to be run. ### 5.2.3 Cause [Task]s MAY be invoked as an effect caused by a prior [Invocation]. Such [Invocation]s SHOULD have a \`cause\` field set to the [Receipt] link of the [Invocation] that caused it. The linked [Receipt] MUST have an \`Effect\` (the \`fx\` field) containing invoked [Task] in the \`run\` field. ### 5.2.4 Authorization The \`auth\` field MUST contain a link to the [Authorization] that authorizes invoked [Task] in the \`run\` field. The linked [Authorization] MUST contain \`run\` in its \`scope\`. ### 5.2.4 Proofs The \`prf\` field MUST contain links to any UCANs that provide the authority to perform this task. All of the outermost proofs MUST have \`aud\` field set to the [Executor]'s DID. All of the outmost proofs MUST have \`iss\` field set to the [Invoker]'s DID. ### 5.2.6 Metadata The OPTIONAL \`meta\` field MAY be used to include human-readable descriptions, tags, execution hints, resource limits, and so on. If present, the \`meta\` field MUST contain a map with string keys. The contents of the map are left undefined to encourage extensible use. If \`meta\` field is not present, it is implicitly a \`unit\` represented as an empty map. ## 5.3 DAG-JSON Example ### 5.3.1 Single Invocation ${LINKS} `34:T740,FX = Syntax.md` ## 7 Effect The result of an [Invocation] MAY include a request for further actions to be performed via "effects". This enables several things: a clean separation of pure return values from reuqesting impure tasks to be performed by the runtime, and gives the runtime the control to decide how (or if!) more work should be performed. Effects describe requests for future work to be performed. All [Invocation]s in an [Effect] block MUST be treated as concurrent, unless explicit data dependencies between them exist via promise [Pipelines]. The \`fx\` block contains two fields: \`fork\` and \`join\`. [Task]s listed in the \`fork\` field are first-class and only ordered by promises; they otherwise SHOULD be considered independent and equal. As such, atomic guarintees such as failure of one effect impling failure of other effects if left undefined. The \`join\` field describes an OPTIONAL "special" [Invocation] which instruct the [Executor] that the [Task] [Invocation] is a continuation of the previous Invocation. This roughly emulates a virtual thread which terminates in an Invocation that produces Effect without a \`join\` field. Tasks in the \`fork\` field MAY be related to the Task in the \`join\` field if there exists a Promise referencing either Task. If such a promise does not exist, then they SHOULD be treated as entirely separate and MAY be scheduled, deferred, fail, retry, and so on entirely separately. ${schema.Effect.source} ## 7.2 Fields ### 7.2.1 Forked Task Invocations The OPTIONAL \`fork\` field, if present MUST be a list of an alphabetically ordered [Task] links. List MUST NOT not contain duplicate entries. ### 7.2.2 Joined Task Invocation The OPTIONAL \`join\` field, if present MUST be set to a [Task] link. ## 7.3 DAG-JSON Examples ### 7.3.1 Effect spawning concurrent threads ${LINKS} `35:T803,ReceiptIntro = Syntax.md` # 8 Receipt A \`Receipt\` is an attestation of the [Result] and requested [Effect]s by a [Task] [Invocation]. A Receipt MUST be signed by the [Executor] or it's delegate. If signed by the delegate, the proof of delegation from the [Executor] to the delegate (the \`iss\` of the receipt) MUST be provided in \`prf\`. **NB: a Receipt does not guarantee correctness of the result!** The statement's veracity MUST be only understood as an attestation from the executor. Receipts MUST use the same version as the invocation that they contain. ## 8.1 Schema ${schema.Receipt.source} ## 8.2 Fields ### 8.2.1 Ran Invocation The \`ran\` field MUST include a link to the [Invocation] that the Receipt is for. ### 8.2.2 Output The \`out\` field MUST contain the value output of the invocation in [Result] format. ### 8.2.3 Effect The OPTIONAL \`fx\` field, if present MUST be set to the caused [Effect]. The [Executor] SHOULD invoke contained [Task] to progress a workflow execution. If \`fx\` does not contain OPTIONAL \`join\` field, it denotes completion of the current execution thread. ### 8.2.4 Metadata Fields The OPTIONAL metadata field MAY be omitted or used to contain additional data about the receipt. This field MAY be used for tags, commentary, trace information, and so on. ### 8.2.5 Receipt Issuer The OPTIONAL \`iss\` field, if present MUST contain the DID of the [Executor] delegate that signed it. If field is present, delegation from [Executor] MUST be included in the \`prf\` field. If \`iss\` field is omitted, Receipt MUST be signed by the [Executor]. ### 8.2.6 Proofs If OPTIONAL \`prf\` field is present, MUST contain link to UCAN delegatation authorizing Receipt Issuer (\`iss\`) to carry [Task] execution. ### 8.2.7 Signature The \`s\` field MUST contain a [Varsig] of the [DAG-CBOR] encoded Receipt without \`s\` field. The signature MUST be generated by the [Executor] or a delegate if OPTIONAL \`iss\` field is set. ## 8.3 DAG-JSON Examples ### 8.3.1 Issued by Executor ${LINKS} `36:T61c,Pipelines = Syntax.md` # 9 Pipelines > Machines grow faster and memories grow larger. But the speed of light is constant and New York is not getting any closer to Tokyo. As hardware continues to improve, the latency barrier between distant machines will increasingly dominate the performance of distributed computation. When distributed computational steps require unnecessary round trips, compositions of these steps can cause unnecessary cascading sequences of round trips > > — [Mark Miller](https://github.com/erights), [Robust Composition](http://www.erights.org/talks/thesis/markm-thesis.pdf) There MAY not be enough information to described an Invocation at creation time. However, all of the information required to construct the next request in a sequence MAY be available in the same Batch, or in a previous (but not yet complete) Invocation. Some invocations MAY require input from set of other invocations. Waiting for each request to complete before proceeding to the next task has a performance impact due to the amount of latency. [Promise pipelining](http://erights.org/elib/distrib/pipeline.html) is a solution to this problem: by referencing a prior invocation, a pipelined invocation can direct the executor to use the output of one invocations into the input of the other. This liberates the invoker from waiting for each step. An [Await] MAY be used as a variable placeholder for a concrete value in a [Task] [Invocation] output, waiting on a previous step to complete. For example, consider the following invocation batch: ${LINKS} `37:T7ef,AwaitInto = Syntax.md` Any [Task] field other besides \`call\` MAY be substituted with \`Await\`. The \`call\` field is critical in understanding what kind of action will be performed and CAN NOT be substituded with \`Await\`. An [Await] MAY be used across [Invocation]s with a same [Authorization], or across [Invocation]s with different [Authorization] and MAY even be across multiple Invokers and Executors. As long as the invocation can be resolved, it MAY be promised. This is sometimes referred to as ["promise pipelining"](http://erights.org/elib/distrib/pipeline.html). ## Await An \`Await\` describes the eventual output of the referenced [Task] invocation. An \`Await\` MUST resolve to an output [Result] with \`await/*\` variant. If unwrapping success or failure case is desired, corresponding \`await/ok\` or \`await/error\` variants MUST be used. ## 9.1 Schema ${schema.Await.source} #### 9.2 Variants ##### 9.2.1 Success The successful output of the [Task] MAY be referenced by wrapping the [Task] in the \`"await/ok"\` tag. [Executor] MUST fail [Task] that \`Await\`s successful output of the failed [Task]. [Executor] MUST substitute [Task] field set to the [Await] of the successful [Task] with an (unwrapped) \`ok\` value of the output. ##### 9.2.2 Failure The failed output of the [Task] MAY be referenced by wrapping the [Task] in the \`"await/error"\` tag. [Executor] MUST fail [Task] that \`Await\`s failed output of the successful [Task]. [Executor] MUST substitute [Task] field set to the [Await] of the failed [Task] with an (unwrapped) \`error\` value of the output. ##### 9.2.3 Result The [Result] output of the [Task] MAY be reference by wrapping the [Task] in the \`"await/*"\` tag. [Executor] MUST substitute [Task] field set to the [Await] of the [Task] with a \`Result\` value of the output. ## 9.3 Dataflow Pipelining uses [Await] as inputs to determine the required dataflow graph. The following examples both express the following dataflow graph: ### 9.3.1 Batched ${LINKS} `38:Ta23,PriorArt = Syntax.md` # 10 Prior Art [ucanto RPC](https://github.com/web3-storage/ucanto) from DAG House is a production system that uses UCAN as the basis for an RPC layer. The [Capability Transport Protocol (CapTP)](http://erights.org/elib/distrib/captp/index.html) is one of the most influential object-capability systems, and forms the basis for much of the rest of the items on this list. The [Object Capability Network (OCapN)](https://github.com/ocapn/ocapn) protocol extends CapTP with a generalized networking layer. It has implementations from the [Spritely Institute](https://www.spritely.institute/) and [Agoric](https://agoric.com/). At time of writing, it is in the process of being standardized. [Electronic Rights Transfer Protocol (ERTP)](https://docs.agoric.com/guides/ertp/) builds on top of CapTP for blockchain & digital asset use cases. [Cap 'n Proto RPC](https://capnproto.org/) is an influential RPC framework [based on concepts from CapTP](https://capnproto.org/rpc.html#specification). # 11 Acknowledgements Many thanks to [Mark Miller](https://github.com/erights) for his [pioneering work](http://erights.org/talks/thesis/markm-thesis.pdf) on [capability systems](http://erights.org/). Many thanks to [Luke Marsen](https://github.com/lukemarsden) and [Simon Worthington](https://github.com/simonwo) for their feedback on invocation model from their work on [Bacalhau](https://www.bacalhau.org/) and [IPVM](https://github.com/ipvm-wg). Many thanks to [Zeeshan Lakhani](https://github.com/zeeshanlakhani) for his many suggestions, references, clarifications, and suggestions on how to restructure sections for clarity. Thanks to [Marc-Antoine Parent](https://github.com/maparent) for his discussions of the distinction between declarations and directives both in and out of a UCAN context. Many thanks to [Quinn Wilton](https://github.com/QuinnWilton) for her discussion of speech acts, the dangers of signing canonicalized data, and ergonomics. Thanks to [Blaine Cook](https://github.com/blaine) for sharing their experiences with OAuth 1, irreversible design decisions, and advocating for keeping the spec simple-but-evolvable. Thanks to [Philipp Krüger](https://github.com/matheus23/) for the enthusiastic feedback on the overall design and encoding. Thanks to [Christine Lemmer-Webber](https://github.com/cwebber) for the many conversations about capability systems and the programming models that they enable. Thanks to [Rod Vagg](https://github.com/rvagg/) for the clarifications on IPLD Schema implicits and the general IPLD worldview. ${LINKS} `39:Tbae,class Agent { static expiration = new Date("June 01, 2023").getTime() / 1000; constructor({ issuer, audience, authority = issuer, proofs = [] }) { this.issuer = issuer; this.audience = audience; this.authority = authority; this.proofs = proofs; this.expiration = new Date("June 01, 2023").getTime() / 1000; this.Transaction = Transaction; } static async connect({ issuer, audience, authority = issuer, api = {} }) { return new this({ issuer, audience, authority, proofs: authority.did() === issuer.did() ? [] : [ await delegate({ issuer: authority, audience: issuer, capabilities: [ { can: "*", with: "did:*" } ], expiration: Agent.expiration }) ] }).provide(api); } sign(payload) { return this.issuer.sign(payload); } delegate({ can, with: uri, nb = {}, expiration = Agent.expiration }) { return delegate({ issuer: this.issuer, audience: this.audience, capabilities: [ { can, with: uri, ...(isEmpty(nb) ? {} : { nb }) } ], expiration }); } run(source) { return new Task({ ...source, agent: this }); } invoke(source) { return this.run(source).invoke(); } execute(run = []) { return new this.Transaction({ agent: this, run: run.map((task) => task.invoke()) }); } receipt(source) { return new Receipt({ ...source, agent: this }); } provide(api) { const descriptor = Agent.build(api, [], this); Object.defineProperties(this, descriptor); this.Transaction = class Transaction extends this.Transaction {}; Object.defineProperties(this.Transaction.prototype, descriptor); return this; } static build(api, path = [], target = {}) { const descriptor = {}; for (const [key, value] of Object.entries(api)) { if (value === true) { const ability = [...path, key].join("/"); descriptor[key] = { enumerable: true, value(on, input = {}, { nonce = "" } = {}) { const top = this.top || this; return top.run({ on, call: ability, input, nonce }); } }; } else { class API { constructor(top) { this.top = top; } } Object.defineProperties( API.prototype, Agent.build(api[key], [...path, key]) ); descriptor[key] = { enumerable: true, configurable: true, get() { const api = new API(this.top || this); Object.defineProperty(this, key, { value: api }); return api; } }; } } return descriptor; } }3a:T580,class Task { constructor({ agent, call, on, input = {}, nonce = "" }) { this.agent = agent; this.call = call; this.on = on; this.input = input; this.nonce = nonce; } *tasks() { if (typeof this.on.tasks === "function") { yield* this.on.tasks(); } for (const value of Object.values(this.input)) { if (value && typeof value.tasks === "function") { yield* value.tasks(); } } yield this; } invoke(options) { return new Invocation({ ...options, agent: this.agent, run: this }); } execute() { return this.agent.execute([this]); } transaction() { return new Transaction({ agent: this.agent }).invoke(this); } await() { return new AwaitResult(this); } receipt(source) { return this.invoke().receipt(source); } async build() { const { result } = await Builder.build(this); return result; } [show.symbol] = { Task: async (task) => Syntax({ json: await format(task) }), Invocation: async (task) => Syntax({ json: await format(task.invoke()) }), Authorization: async (task) => Syntax({ json: await format(await task.execute().authorize()) }), CAR: async (task) => Syntax({ json: await format(task.invoke().execute()) }), Blocks: async (task) => Syntax({ json: await format(await task.execute().blocks()) }) }; }3b:T1902,class Builder { static build(source) { return new Builder(source).build(source); } constructor(source) { this.source = source; this.artifacts = new WeakMap(); this.tasks = []; this.invocations = []; this.blocks = []; this.roots = []; } fork(source) { const builder = new Builder(source); builder.artifacts = this.artifacts; return builder; } async buildCause(source) { const { result } = await Builder.build(source); return result; } async buildTransaction(source) { const promises = []; for (const invocation of source.run) { promises.push(await this.buildPromise(invocation)); } const auth = await this.buildAuth(); for (const promise of promises) { await promise.compile(auth); } this.blocks.push(auth); return compileCAR({ roots: this.roots, blocks: this.blocks }); } async buildEffect(source) { const effects = {}; if (source.join) { const { cid } = await this.buildTask(source.join); effects.join = cid; } if (source.fork && source.fork.length > 0) { effects.fork = []; for (const each of source.fork || []) { const { cid } = await this.buildTask(each); effects.fork.push(cid); } } return compileCBOR(effects); } async buildReceipt(source) { const { agent, out, meta } = source; const prf = []; for (const proof of agent.proofs) { prf.push(proof.cid); } const builder = this.fork(source.run); const { cid } = await builder.buildInvocation(source.ran); const { value: fx } = await this.buildEffect(source.fx); const payload = { ran: cid, out, ...(isEmpty(fx) ? {} : { fx }), ...(isEmpty(meta) ? {} : { meta }), ...(agent.issuer.did() !== agent.authority.did() ? { iss: agent.issuer.did() } : {}), ...(prf.length ? { prf } : {}) }; const { bytes } = await compileCBOR(payload); return compileCBOR({ ...payload, s: await agent.sign(bytes) }); } async buildSet(source) { const set = {}; for (const member of source) { const value = await this.buildSource(member); set[value.cid] = value; } return set; } async buildSource(source) { if (!source) { return source; } else if (source.constructor.name === "Await") { return this.buildAwait(source); } else if (source.constructor.name === "Task") { return this.buildTask(source); } else if (source.constructor.name === "Invocation") { return this.buildInvocation(source); } else if (source.constructor.name === "Transaction") { return this.buildTransaction(source); } else if (source.constructor.name === "Receipt") { return this.buildReceipt(source); } else if (source.constructor.name === "Effect") { return this.buildEffect(source); } else if (ArrayBuffer.isView(source)) { return source; } else if (Array.isArray(source)) { const array = []; for (const value of source) { array.push(await this.buildSource(value)); } return array; } else if (source instanceof Set) { return this.buildSet(source); } else if (typeof source === "object") { const object = {}; for (const [key, value] of Object.entries(source)) { object[key] = await this.buildSource(value); } return object; } else { return source; } } async buildAuth() { const scope = this.tasks .map((task) => task.cid) .sort((left, right) => (`${left}` < `${right}` ? 1 : 0)); const bytes = CBOR.encode(scope); const auth = await compileCBOR({ scope, s: await this.source.agent.sign(bytes) }); this.auth = auth; console.log(this.auth); return auth; } async buildAwait({ branch, task }) { const { cid } = task.constructor.name === "Task" ? await this.buildTask(task) : { cid: task }; return { [`await/${branch}`]: cid }; } buildResource(source) { if (source.constructor.name === "Await") { return this.buildAwait(source); } else { return source; } } async buildTask(source) { const artifact = this.artifacts.get(source); if (artifact) { return artifact; } else { const { nonce } = source; const input = await this.buildSource(source.input); const artifact = { source, ...(await compileCBOR({ on: await this.buildResource(source.on), call: source.call, ...(isEmpty(input) ? {} : { input }), ...(nonce === "" ? {} : { nnc: nonce }) })) }; this.tasks.push(artifact); this.blocks.push(artifact); this.artifacts.set(source, artifact); return artifact; } } async build() { this.result = await this.buildSource(this.source); return this; } async buildPromise(source) { const prf = await source.buildProofs(); const cause = await this.buildCause(source.cause); const run = await this.buildTask(source.run); const meta = await this.buildSource(source.meta); return { compile: async (auth) => { const artifact = this.artifacts.get(source); if (artifact) { return artifact; } else { const artifact = { ...(await compileCBOR({ v: source.version, run: run.cid, ...(auth ? { auth: auth.cid } : {}), ...(cause ? { cause: cause.cid } : {}), ...(isEmpty(meta) ? {} : { meta }), prf })), source }; this.blocks.push(artifact); this.artifacts.set(source, artifact); if (auth) { this.invocations.push(artifact); this.roots.push(artifact.cid); } return artifact; } } }; } async buildInvocation(source) { const artifact = this.artifacts.get(source); if (artifact) { return artifact; } else { const promise = await this.buildPromise(source); if (this.source === source) { const auth = await this.buildAuth(); const result = await promise.compile(auth); this.blocks.push(auth); return result; } else { return promise.compile(); } } } }3c:T61e,class Invocation { constructor({ version = "0.1.0", run, cause = null, meta = {}, proofs = [], agent = run.agent }) { this.version = version; this.run = run; this.cause = cause; this.meta = meta; this.proofs = proofs; this.agent = agent; } get [Symbol.toStringTag]() { return "Invocation"; } async buildProofs() { const prf = []; for (const proof of this.proofs) { prf.push(proof.cid); } if (prf.length === 0) { const proof = await this.agent.delegate({ can: this.run.call, with: this.run.on }); prf.push(proof.cid); } return prf; } *tasks() { yield* this.run.tasks(); for (const value of Object.values(this.meta)) { if (value && typeof value.tasks === "function") { yield* value.tasks(); } } } receipt(source) { return new Receipt({ agent: this.agent, ...source, ran: this }); } execute() { return new this.agent.Transaction({ agent: this.agent, run: [this] }); } await() { return new AwaitResult(this.run); } [show.symbol] = { Invocation: async (me) => Syntax({ json: await format(me) }), Task: async ({ run }) => Syntax({ json: await format(run) }), Authorization: async (me) => Syntax({ json: await format(await me.execute().authorize()) }), CAR: async (me) => Syntax({ json: await format(me.execute()) }), Blocks: async (me) => Syntax({ json: await format(await me.execute().blocks()) }) }; }3d:T4a3,class Transaction { constructor({ run = [], agent }) { this.run = run; this.agent = agent; } invoke(task) { const run = [...this.run]; let cause = undefined; // for (const task of tasks) { cause = this.agent.run(task).invoke({ cause }); run.push(cause); // } return this.agent.transaction(run); } build() { return Builder.build(this); } async blocks() { const { blocks } = await this.build(); const result = {}; for (const block of blocks) { result[block.cid] = block; } return result; } async authorize() { const { auth } = await this.build(); return auth; } *tasks() { for (const invocation of this.run) { yield* invocation.tasks(); } } [show.symbol] = { CAR: async (tr) => Syntax({ json: await format(tr) }), Blocks: async (tr) => Syntax({ json: await format(await tr.blocks()) }), Tasks: async (tr) => Syntax({ json: await format(new Set([...tr.tasks()])) }), Invocations: async ({ run }) => Syntax({ json: await format(new Set(run)) }), Authorization: async (tr) => Syntax({ json: await format(await this.authorize()) }) }; }3e:T52f,Syntax = { function Syntax(source) { for (const name in source) { return Syntax.md`${fence}${name} ${source[name]} ${fence} `; } } const fence = "```"; return Object.assign(Syntax, { raw: (...args) => Syntax.md`${fence} ${String.raw(...args)} ${fence} `, html: (template, ...args) => { const source = args.map(($) => typeof $ === "string" ? $ : $ && $.source ? $.source : "" ); return Object.assign(html(template, ...args), { source: String.raw(template, ...source) }); }, md: (...args) => { const source = String.raw(...args) .replaceAll("~~~", "```") .replaceAll("\\`", "`"); return Object.assign(md`${source}`, { source }); }, mermaid: (template, ...args) => { return Object.assign(mermaid(template, ...args), { source: String.raw(template, ...args) }); }, js: (...args) => { return Syntax({ js: String.raw(...args) }); }, ipldsch: (...args) => { const { types } = fromDSL(String.raw(...args)); const schema = Syntax({ ipldsch: toDSL({ types }) }); for (const [key, value] of Object.entries(types)) { schema[key] = Syntax({ ipldsch: toDSL({ types: { [key]: types[key] } }) }); } return schema; } }); }3f:T409,show = Object.assign( async function* show(source, defaultName) { const on = (element, eventType) => new Promise((resolve) => { element.addEventListener(eventType, resolve, { once: true }); }); const subject = typeof source === "function" ? await source() : source; const views = { ...(subject && subject[show.symbol] ? subject[show.symbol] : {}), Inspector: inspect, ...(typeof source === "function" ? { Source: () => Syntax({ js: String(source) }) } : {}) }; const keys = Object.keys(views); const select = Inputs.select(keys, { value: defaultName }); while (true) { const view = views[select.value]; const target = typeof view === "function" ? await view(subject) : view; const element = document.createElement("div"); element.append(select); yield Syntax.html`${select} ${target instanceof Element ? target : inspect(target)} `; await on(select, "change"); } }, { symbol: Symbol.for("inspect") } )40:T503,source = URL.createObjectURL( new Blob([ ...[ intro, schema, taskIntro, sendMailExample, pipelineNote, pipelineExample, Syntax({ js: String(taskPipeline) }), taskField, publishBlogExample, sendEmailInto, sendEmailExample, runWASMTitle, runWASMExample, sendEmailInto, sendEmailExample, runWASMTitle, runWASMExample, authIntro, authExample, invocationIntro, singleInvocationExample, multipleInvocationTitle, multipleInvocationsExample, CausalInvocations, causalInvocationExample, Result, FX, forkExample, JoinExample, joinExample, ForkJoinExample, forkJoinExample, ReceiptIntro, basicReceiptExample, delegatedReceiptTitle, delegatedReceiptExample, ReceiptWithEffects, receiptWithFXExample, Pipelines, pipelineExmapleNote, pipelineCode, pipelineExmapleNote, Syntax({ js: String(notifyEditorsExample) }), AwaitInto, BatchFlow, batchExample, Serial, SerialFlow, serialBegin, serialEnd, PriorArt ].map((part) => part.source.replace(LINKS, "")), "\n\n", LINKS ]) )41:[] 2e:{"title":"UCAN Invocation Specification v0.1.0","cells":[{"id":0,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":1157,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":3312,"value":"taskIntro = Syntax.md`# 3 Task\n\nA Task is the smallest unit of work that can be requested from a UCAN. It describes one \\`(resource, ability, input)\\` triple. The \\`input\\` field is free form, and depend on the specific resource and ability being interacted with, and is not described in this specification.\n\nUsing the JavaScript analogy from the introduction, a Task is similar to wrapping a call in an anonymous function:\n${LINKS}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4960,"value":"sendMailExample = show(sendMail)","pinned":false,"hidden":false,"mode":"ojs"},{"id":4955,"value":"sendMail = () =>\n msg.send(\"mailto:alice@example.com\", {\n to: [\"bob@example.com\", \"carol@example.com\"],\n subject: \"hi\",\n body: \"world\"\n })","pinned":true,"hidden":false,"mode":"ojs"},{"id":4979,"value":"pipelineNote = Syntax.md`\nLater, when we explore promise [pipelines], this also includes capturing the promise:\n${LINKS}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4989,"value":"pipelineExample = show(taskPipeline().execute(), \"Tasks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":4985,"value":"taskPipeline = () => {\n // Pseudocode\n const mailingList = crud.read(\"https://exmaple.com/mailinglist\");\n const sendEmail = msg.send(\"mailto://alice@example.com\", {\n to: mailingList.await().ok,\n subject: \"hello\",\n body: \"world\"\n });\n\n return sendEmail;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":4951,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":1659,"value":"publishBlogExample = show(() =>\n crud.create(\"https://example.com/blog/posts\", {\n headers: {\n \"content-type\": \"application/json\"\n },\n payload: {\n title: \"How UCAN Tasks Changed My Life\",\n body: \"This is the story of how one spec changed everything...\",\n topics: [\"authz\", \"journal\"],\n draft: true\n }\n })\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3397,"value":"sendEmailInto = Syntax.md`### 3.3.2 Sending Email`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1723,"value":"sendEmailExample = show(() =>\n msg.send(\n \"mailto:akiko@example.com\",\n {\n to: [\"boris@example.com\", \"carol@example.com\"],\n subject: \"Coffee\",\n body: \"Hey you two, I'd love to get coffee sometime and talk about UCAN Tasks!\"\n },\n {\n meta: {\n \"dev/priority\": \"high\",\n \"dev/tags\": [\"friends\", \"coffee\"]\n }\n }\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3399,"value":"runWASMTitle = Syntax.md`### 3.3.3 Running WebAssembly`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1728,"value":"runWASMExample = show(() =>\n wasm.run(\n \"data:application/wasm;base64,AHdhc21lci11bml2ZXJzYWwAAAAAAOAEAAAAAAAAAAD9e7+p/QMAkSAEABH9e8GowANf1uz///8UAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP////8AAAAACAAAACoAAAAIAAAABAAAACsAAAAMAAAACAAAANz///8AAAAA1P///wMAAAAlAAAALAAAAAAAAAAUAAAA/Xu/qf0DAJHzDx/44wMBqvMDAqphAkC5YAA/1mACALnzB0H4/XvBqMADX9bU////LAAAAAAAAAAAAAAAAAAAAAAAAAAvVXNlcnMvZXhwZWRlL0Rlc2t0b3AvdGVzdC53YXQAAGFkZF9vbmUHAAAAAAAAAAAAAAAAYWRkX29uZV9mAAAADAAAAAAAAAABAAAAAAAAAAkAAADk////AAAAAPz///8BAAAA9f///wEAAAAAAAAAAQAAAB4AAACM////pP///wAAAACc////AQAAAAAAAAAAAAAAnP///wAAAAAAAAAAlP7//wAAAACM/v//iP///wAAAAABAAAAiP///6D///8BAAAAqP///wEAAACk////AAAAAJz///8AAAAAlP///wAAAACM////AAAAAIT///8AAAAAAAAAAAAAAAAAAAAAAAAAAET+//8BAAAAWP7//wEAAABY/v//AQAAAID+//8BAAAAxP7//wEAAADU/v//AAAAAMz+//8AAAAAxP7//wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAU////pP///wAAAAAAAQEBAQAAAAAAAACQ////AAAAAIj///8AAAAAAAAAAAAAAADQAQAAAAAAAA==\",\n {\n func: \"add_one\",\n args: [42]\n }\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3316,"value":"authIntro = Syntax.md`# 4 Authorization\n\nAn [Authorization] is cryptographically signed data set. It represents an authorization to run [Task]s in that are included in \\`scope\\` data set.\n\n## 4.1 Schema\n\n${schema.Authorization.source}\n\n### 4.2 Fields\n\n#### 4.2.1 Authorization Scope\n\nThe \\`scope\\` field MUST be a set of links been authorized. It SHOULD be encoded as an alphabetically ordered list without duplicates.\n\nIf \\`scope\\` field is omitted, it is implicitly a an empty list and has no practical use as it authorizes nothing.\n\n### 4.2.2 Signature\n\nThe \\`s\\` field MUST contain a [Varsig] of the [DAG-CBOR] encoded \\`scope\\` field.\n\n## 4.3 DAG-JSON Example\n${LINKS}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2416,"value":"authExample = show(() => {\n const mailingList = crud.read(\"https://exmaple.com/mailinglist\");\n const notifyList = msg.send(\"mailto://alice@example.com\", {\n to: mailingList.await().ok,\n subject: \"hello\",\n body: \"world\"\n });\n\n return notifyList;\n}, \"Authorization\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3318,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":1743,"value":"singleInvocationExample = show(\n () =>\n crud.create(\"https://example.com/blog/posts\", {\n headers: {\n \"content-type\": \"application/json\"\n },\n payload: {\n title: \"How UCAN Tasks Changed My Life\",\n body: \"This is the story of how one spec changed everything...\",\n topics: [\"authz\", \"journal\"],\n draft: true\n }\n }),\n \"Blocks\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3425,"value":"multipleInvocationTitle = Syntax.md`### 5.3.2 Multiple Invocations`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1748,"value":"multipleInvocationsExample = show(\n () =>\n agent.execute([\n crud.create(\"https://example.com/blog/posts\", {\n headers: {\n \"content-type\": \"application/json\"\n },\n payload: {\n title: \"How UCAN Tasks Changed My Life\",\n body: \"This is the story of how one spec changed everything...\",\n topics: [\"authz\", \"journal\"],\n draft: true\n }\n }),\n msg.send(\n \"mailto:akiko@example.com\",\n {\n to: [\"boris@example.com\", \"carol@example.com\"],\n body: \"Hey you two, I'd love to get coffee sometime and talk about UCAN Tasks!\",\n subject: \"Coffee\"\n },\n {\n meta: {\n \"dev/priority\": \"high\",\n \"dev/tags\": [\"friends\", \"coffee\"]\n }\n }\n )\n ]),\n \"Blocks\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3432,"value":"CausalInvocations = Syntax.md`### 5.3.3 Causal Invocations`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2461,"value":"causalInvocationExample = show(async () => {\n // Publish a new web site\n const publishSite = site.publish(\"https://example.dev\", {\n headers: { \"content-type\": \"text/html\" },\n body: \"Hello World!\"\n });\n\n // Emulate a receipt that succeeds publishing and\n // schedules a DNS update\n const receipt = publishSite.invoke().receipt({\n out: { ok: { status: 200 } },\n fx: {\n join: crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n })\n }\n });\n\n // Get reference to DNS update invocation that is causaly linked\n // with publishSite\n return receipt.join();\n}, \"Blocks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3320,"value":"Result = Syntax.md`\n# 6 Result\n\nA \\`Result\\` records the output of the [Task], as well as its success or failure state.\n\n## 6.1 Schema\n\n${schema.Result.source}\n\n## 6.2 Variants\n\n## 6.2.1 Success\n\nThe success branch MUST contain the value returned from a successful [Task] wrapped in the \\`\"ok\"\\` tag. The exact shape of the returned data is left undefined to allow for flexibility in various Task types.\n\n\n~~~json\n{ \"ok\": 42 }\n~~~\n\n## 6.2.2 Failure\n\nThe failure branch MAY contain detail about why execution failed wrapped in the \"error\" tag. It is left undefined in this specification to allow for [Task] types to standardize the data that makes sense in their contexts.\n\nIf no information is available, this field SHOULD be set to \\`{}\\`.\n\n~~~json\n{\n \"error\": {\n \"dev/reason\": \"unauthorized\",\n \"http/status\": 401\n }\n}\n~~~\n\n${LINKS}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3325,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":3556,"value":"forkExample = show(() => {\n // Publish a new web site\n const publishSite = site.publish(\"https://example.dev\", {\n headers: { \"content-type\": \"text/html\" },\n body: \"Hello World!\"\n });\n\n // Emulate a receipt that succeeds publishing and\n // schedules a DNS update\n return publishSite.receipt({\n out: { ok: { status: 200 } },\n fx: {\n // And concurrently notify alice & carol about new site\n fork: [\n msg.send(\"mailto://bot@example.com\", {\n to: \"carol@example.com\",\n subject: \"Site was updated!\"\n }),\n msg.send(\"mailto://bot@example.com\", {\n to: \"alice@example.com\",\n subject: \"Site was updated!\"\n })\n ]\n }\n });\n}, \"Effect\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3585,"value":"JoinExample = Syntax.md`### 7.3.2 Effect continuing thread execution`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3553,"value":"joinExample = show(() => {\n // Publish a new web site\n const publishSite = site.publish(\"https://example.dev\", {\n headers: { \"content-type\": \"text/html\" },\n body: \"Hello World!\"\n });\n\n // Emulate a receipt that succeeds publishing and\n // schedules a DNS update\n return publishSite.receipt({\n out: { ok: { status: 200 } },\n fx: {\n // Update DNS\n join: crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n })\n }\n });\n}, \"Effect\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3591,"value":"ForkJoinExample = Syntax.md`### 7.3.3 Effect with fork & join`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3558,"value":"forkJoinExample = show(() => {\n // Publish a new web site\n const publishSite = site.publish(\"https://example.dev\", {\n headers: { \"content-type\": \"text/html\" },\n body: \"Hello World!\"\n });\n\n // Emulate a receipt that succeeds publishing and\n // schedules a DNS update\n return publishSite.receipt({\n out: { ok: { status: 200 } },\n fx: {\n // Update DNS\n join: crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n }),\n // And concurrently notify alice & carol about new site\n fork: [\n msg.send(\"mailto://bot@example.com\", {\n to: \"carol@example.com\",\n subject: \"Site was updated!\"\n }),\n msg.send(\"mailto://bot@example.com\", {\n to: \"alice@example.com\",\n subject: \"Site was updated!\"\n })\n ]\n }\n });\n}, \"Effect\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3323,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":1844,"value":"basicReceiptExample = show(() => {\n const mailingList = crud.read(\"https://exmaple.com/mailinglist\");\n\n const receipt = mailingList.receipt({\n out: {\n ok: {\n members: [\"bob@example.com\", \"alice@web.mail\"]\n }\n },\n meta: {\n retries: 2,\n time: [400, \"hours\"]\n }\n });\n\n return receipt;\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":3507,"value":"delegatedReceiptTitle = Syntax.md`### 8.3.2 Issued by Delegate`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1850,"value":"delegatedReceiptExample = show(async () => {\n const mailingList = crud.read(\"https://exmaple.com/mailinglist\");\n\n const receipt = mailingList.receipt({\n // Receipt is issued by a worker that acts on behalf of VM\n agent: await Agent.connect({\n issuer: await ed25519.parse(\n \"MgCYKXoHVy7Vk4/QjcEGi+MCqjntUiasxXJ8uJKY0qh11e+0Bs8WsdqGK7xothgrDzzWD0ME7ynPjz2okXDh8537lId8=\"\n ),\n authority: await ed25519\n .parse(\n \"MgCYKXoHVy7Vk4/QjcEGi+MCqjntUiasxXJ8uJKY0qh11e+0Bs8WsdqGK7xothgrDzzWD0ME7ynPjz2okXDh8537lId8=\"\n )\n .withDID(\"did:web:ucan.run\")\n }),\n out: {\n ok: {\n members: [\"bob@example.com\", \"alice@web.mail\"]\n }\n },\n meta: {\n retries: 2,\n time: [400, \"hours\"]\n }\n });\n\n return receipt;\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":3509,"value":"ReceiptWithEffects = Syntax.md`### 7.3.8 Receipts with effects`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3539,"value":"receiptWithFXExample = show(() => {\n // Publish a new web site\n const publishSite = site.publish(\"https://example.dev\", {\n headers: { \"content-type\": \"text/html\" },\n body: \"Hello World!\"\n });\n\n // Emulate a receipt that succeeds publishing and\n // schedules a DNS update\n const receipt = publishSite.receipt({\n out: { ok: { status: 200 } },\n fx: {\n // Update DNS\n join: crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n }),\n // And concurrently notify alice & carol about new site\n fork: [\n msg.send(\"mailto://bot@example.com\", {\n to: \"carol@example.com\",\n subject: \"Site was updated!\"\n }),\n msg.send(\"mailto://bot@example.com\", {\n to: \"alice@example.com\",\n subject: \"Site was updated!\"\n })\n ]\n }\n });\n\n return receipt;\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":3328,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":4585,"value":"pipelineCode = show(notifyEditorsExample, \"Blocks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3635,"value":"pipelineExmapleNote = Syntax.md`\nBy analogy, above examples can be interpreted roughly as follows:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3643,"value":"notifyEditorsExample = () => {\n const createDraft = crud.create(\"https://example.com/blog/posts\", {\n payload: {\n title: \"How UCAN Tasks Changed My Life\",\n body: \"This is the story of how one spec changed everything...\"\n }\n });\n\n const getEditors = crud.read(\"https://example.com/users/editors\");\n\n const notify = msg.send(\"mailto:akiko@example.com\", {\n to: createDraft.await().ok,\n subject: \"Coffee\",\n body: getEditors.await().ok\n });\n\n return notify;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":3619,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":5112,"value":"BatchFlow = Syntax.mermaid`\nflowchart BR\n update-dns(\"with: dns:example.com?TYPE=TXT\n do: crud/update\")\n notify-bob(\"with: mailto://alice@example.com\n do: msg/send\n to: bob@example.com\")\n notify-carol(\"with: mailto://alice@example.com\n do: msg/send\n to: carol@example.com\")\n\n log-as-done(\"with: https://example.com/report\n do: crud/update\")\n\n update-dns --> notify-bob --> log-as-done\n update-dns --> notify-carol --> log-as-done\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3674,"value":"batchExample = show(() => {\n const updateDNS = crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n });\n\n const notifyBob = msg.send(\"mailto://alice@example.com\", {\n to: \"bob@example.com\",\n subject: \"DNSLink for example.com\",\n body: updateDNS.await().ok\n });\n\n const notifyCarol = msg.send(\"mailto://alice@example.com\", {\n to: \"carol@example.com\",\n subject: \"Hey Carol, DNSLink was updated!\",\n body: updateDNS.await().ok\n });\n\n const logDone = crud.update(\"https://example.com/report\", {\n payload: {\n from: \"mailto://alice@exmaple.com\",\n to: [\"bob@exmaple.com\", \"carol@example.com\"],\n event: \"email-notification\"\n },\n _: [notifyBob.await().ok, notifyCarol.await().ok]\n });\n\n return logDone;\n}, \"Blocks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3622,"value":"Serial = Syntax.md`### 9.4.2 Serial`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3665,"value":"SerialFlow = Syntax.mermaid`\nflowchart TB\n update-dns(\"with: dns:example.com?TYPE=TXT\n do: crud/update\")\n notify-bob(\"with: mailto://alice@example.com\n do: msg/send\n to: bob@example.com\")\n notify-carol(\"with: mailto://alice@example.com\n do: msg/send\n to: carol@example.com\")\n\n log-as-done(\"with: https://example.com/report\n do: crud/update\")\n\n subgraph start [ ]\n update-dns\n notify-bob\n end\n\n subgraph finish [ ]\n notify-carol\n log-as-done\n end\n\n update-dns -.-> notify-bob\n update-dns --> notify-carol\n notify-bob --> log-as-done\n notify-carol -.-> log-as-done\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4606,"value":"serialBegin = show(stepOneExample, \"Blocks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3704,"value":"stepOneExample = () => {\n const updateDNS = crud.update(\"dns:example.com?TYPE=TXT\", {\n value: \"hello world\"\n });\n\n const notifyBob = msg.send(\"mailto://alice@example.com\", {\n to: \"bob@example.com\",\n subject: \"DNSLink for example.com\",\n body: updateDNS.await().ok\n });\n\n return notifyBob;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3764,"value":"serialEnd = show(async () => {\n // obtait refs for the invocations from the previous step\n const {\n tasks: [updateDNS, notifyBob]\n } = await stepOneExample().execute().build();\n\n const notifyCarol = msg.send(\"mailto://alice@example.com\", {\n to: \"carol@example.com\",\n subject: \"Hey Carol, DNSLink was updated!\",\n body: Await.ok(updateDNS.cid)\n });\n\n const logDone = crud.update(\"https://example.com/report\", {\n payload: {\n from: \"mailto://alice@exmaple.com\",\n to: [\"bob@exmaple.com\", \"carol@example.com\"],\n event: \"email-notification\"\n },\n _: [Await.ok(notifyBob.cid), notifyCarol.await().ok]\n });\n\n return logDone;\n}, \"Blocks\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":3330,"value":"$38","pinned":false,"hidden":false,"mode":"ojs"},{"id":1506,"value":"-----","pinned":false,"hidden":false,"mode":"md"},{"id":1754,"value":"# Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":3299,"value":"LINKS = ({\n toString: () => `\n[dag-json]: https://ipld.io/docs/codecs/known/dag-json/\n[varsig]: https://github.com/ChainAgnostic/varsig/\n[ucan-ipld]: https://github.com/ucan-wg/ucan-ipld/\n[ucan]: https://github.com/ucan-wg/spec/\n[dag-cbor]: https://ipld.io/specs/codecs/dag-cbor/spec/\n[ipld representation]: https://ipld.io/docs/schemas/features/representation-strategies/\n[lazy-vs-eager]: #112-lazy-vs-eager-evaluation\n[invoker]: #211-invoker\n[executor]: #212-executor\n[task]: #3-task\n[authorization]: #4-authorization\n[invocation]: #5-invocation\n[result]: #6-result\n[effect]: #7-effect\n[receipt]: #8-receipt\n[pipelines]: #9-pipelines\n[promise]: #92-promise\n[await]: #93-await\n`\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":4060,"value":"## User","pinned":false,"hidden":false,"mode":"md"},{"id":2060,"value":"agent = Agent.connect({\n issuer: await ed25519.parse(\n \"MgCZT5vOnYZoVAeyjnzuJIVY9J4LNtJ+f8Js0cTPuKUpFne0BVEDJjEu6quFIU8yp91/TY/+MYK8GvlKoTDnqOCovCVM=\"\n ),\n audience: await ed25519\n .parse(\n \"MgCYKXoHVy7Vk4/QjcEGi+MCqjntUiasxXJ8uJKY0qh11e+0Bs8WsdqGK7xothgrDzzWD0ME7ynPjz2okXDh8537lId8=\"\n )\n .withDID(\"did:web:ucan.run\"),\n api: {\n msg: {\n send: true\n },\n crud: {\n read: true,\n create: true,\n update: true\n },\n wasm: {\n run: true\n },\n site: {\n publish: true,\n sub: {\n method: true\n }\n }\n }\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1300,"value":"msg = agent.msg","pinned":false,"hidden":false,"mode":"ojs"},{"id":1533,"value":"crud = agent.crud","pinned":true,"hidden":false,"mode":"ojs"},{"id":1586,"value":"wasm = agent.wasm","pinned":false,"hidden":false,"mode":"ojs"},{"id":3470,"value":"site = agent.site","pinned":true,"hidden":false,"mode":"ojs"},{"id":2012,"value":"### Lib","pinned":false,"hidden":false,"mode":"md"},{"id":530,"value":"$39","pinned":false,"hidden":false,"mode":"ojs"},{"id":1037,"value":"/**\n * @template {Result} Out\n */\nclass Receipt {\n /**\n * @param {object} source\n * @param {Agent} source.agent\n * @param {Out} source.out\n * @param {Invocation} source.ran\n * @param {Effect} source.fx\n * @param {Record} [source.meta]\n */\n constructor({ agent, out, ran, fx, meta = {} }) {\n this.agent = agent;\n this.out = out;\n this.ran = ran;\n this.meta = meta;\n this.fx = new Effect({ agent, fx });\n }\n\n join() {\n return this.fx.join ? this.fx.join.invoke({ cause: this }) : null;\n }\n\n build() {\n return Builder.build(this);\n }\n format() {\n return format(this);\n }\n\n [show.symbol] = {\n Receipt: async (me) => Syntax({ json: await format(me) }),\n Effect: async ({ fx }) => Syntax({ json: await format(fx) })\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3562,"value":"class Effect {\n constructor({ agent, fx: { fork = [], join = null } = {} }) {\n this.agent = agent;\n this.fork = fork;\n this.join = join;\n }\n\n [show.symbol] = {\n Effect: async (fx) => Syntax({ json: await format(fx) })\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1788,"value":"$3a","pinned":false,"hidden":false,"mode":"ojs"},{"id":1804,"value":"class Await {\n static ok(task) {\n return new Await(task, \"ok\");\n }\n static error(task) {\n return new Await(task, \"error\");\n }\n constructor(task, branch = \"*\") {\n this.task = task;\n this.branch = branch;\n }\n *tasks() {\n yield* this.task.tasks();\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3693,"value":"class AwaitResult extends Await {\n constructor(task) {\n super(task, \"*\");\n }\n get ok() {\n return new Await(this.task, \"ok\");\n }\n get error() {\n return new Await(this.task, \"error\");\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2767,"value":"$3b","pinned":false,"hidden":false,"mode":"ojs"},{"id":1793,"value":"$3c","pinned":false,"hidden":false,"mode":"ojs"},{"id":800,"value":"$3d","pinned":false,"hidden":false,"mode":"ojs"},{"id":2615,"value":"class Request {\n constructor({ blocks = [], roots = [] } = {}) {\n this.blocks = blocks;\n this.roots = roots;\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2272,"value":"class Authorization {\n constructor({ scope = [], agent }) {\n this.scope = scope;\n this.agent = agent;\n }\n run(source) {\n const task = this.agent.run(source);\n this.scope.push(source);\n return task;\n }\n async compile() {\n const scope = [];\n for (const task of this.scope) {\n if (typeof task.compile === \"function\") {\n const { cid } = await task.compile();\n scope.push(cid);\n } else {\n scope.push(task);\n }\n }\n\n const { bytes } = await compileCBOR(\n scope.sort((left, right) => (`${left}` < `${right}` ? 1 : 0))\n );\n\n return await compileCBOR({\n scope,\n s: await this.agent.sign(bytes)\n });\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1978,"value":"## Utils","pinned":false,"hidden":false,"mode":"md"},{"id":4431,"value":"$3e","pinned":false,"hidden":false,"mode":"ojs"},{"id":534,"value":"isEmpty = (source) => Object.keys(source).length === 0","pinned":true,"hidden":false,"mode":"ojs"},{"id":43,"value":"compileCBOR = async (source) => {\n const { cid, bytes, value } = await Block.encode({\n value: source,\n codec: CBOR,\n hasher: sha256\n });\n\n return {\n cid,\n bytes,\n value,\n toJSON() {\n return toDAGJSON(value);\n }\n };\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":458,"value":"compileCAR = ({ blocks, roots = [] }) => {\n const car = { blocks: {}, roots };\n for (const block of blocks) {\n car.blocks[block.cid] = block.toJSON();\n }\n\n return car;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1367,"value":"async function format(source) {\n const { result } = await Builder.build(await source);\n return JSON.stringify(result, null, 2);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":4218,"value":"$3f","pinned":false,"hidden":false,"mode":"ojs"},{"id":4942,"value":"Turns given source into a DAG-JSON object, but retains original field order which is desired for the the readability of produced output","pinned":false,"hidden":false,"mode":"md"},{"id":2274,"value":"toDAGJSON = (source) => reorder(JSON.parse(json.format(source)), source)","pinned":false,"hidden":false,"mode":"ojs"},{"id":2304,"value":"function reorder(data, by) {\n const output = {};\n for (const [key, value] of Object.entries(by)) {\n if (\n value &&\n typeof value === \"object\" &&\n (value[\"/\"] ? value[\"/\"] !== value.bytes : true) &&\n !Array.isArray(value) &&\n !ArrayBuffer.isView(value)\n ) {\n output[key] = reorder(data[key], value);\n } else {\n output[key] = data[key];\n }\n }\n return output;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":4720,"value":"---------------","pinned":false,"hidden":false,"mode":"md"},{"id":4721,"value":"$40","pinned":false,"hidden":false,"mode":"ojs"},{"id":4776,"value":"🔬 View Source\n
\n⬇️ Download Source","pinned":false,"hidden":false,"mode":"html"},{"id":1777,"value":"## Imports","pinned":false,"hidden":false,"mode":"md"},{"id":5,"value":"import { json, CBOR, Block, Link, sha256, CID } from \"@gozala/ipld\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":41,"value":"import { delegate, Signer, ed25519, UCAN } from \"@gozala/ucanto\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":1152,"value":"import { fromDSL, toDSL } from \"@gozala/ipld-schema\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":4363,"value":"import { inspect } from \"@gozala/inspect\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W41","stdlib":"1","titling":"auto"}