docs: a set of diagrams on Zoe and Zcf datastores and initialization

packages/zoe/docs/ZcfDataInitialization.puml

@@ -0,0 +1,50 @@
+@startuml Zoe/ZCF dataStore initialization
+
+actor bootstrap
+
+box Zoe Vat
+participant ZoeService
+participant StartInstance
+participant InstanceStorageManager
+end box
+
+box Zcf Vat
+participant vatRoot
+participant ZcfZygote
+participant contract
+end box
+
+bootstrap -> ZoeService : install(bundle)
+bootstrap <- ZoeService : <font color=gray><size:12>installation
+bootstrap -> ZoeService : startInstance(installation)
+ZoeService -> StartInstance : startInstance(\ninstallation, \nissuerKeywordRecord\nterms, privateArgs)
+StartInstance -> StartInstance : initialize instance state
+StartInstance -> InstanceStorageManager : makeInstanceStorageManager
+InstanceStorageManager -> vatRoot : createZcfVat(bundle)
+note right
+{ zoeService, invitationIssuer } = vatParameters;
+end note
+
+vatRoot -> ZcfZygote : makeZcfZygote(powers, zoeService,\ninvitationIssuer, bundle, baggage)
+ZcfZygote -> ZcfZygote : createSeatManager()
+ZcfZygote -> ZcfZygote : makeInstanceRecordStorage()
+ZcfZygote -> ZcfZygote : makeEmptySeatKit = () => {...}
+ZcfZygote -> ZcfZygote : makeHandleOfferObj = (...) => {...}
+ZcfZygote -> contract : evaluateContract(bundle)
+ZcfZygote /- contract : <font color=gray><size:12>start
+
+vatRoot /- ZcfZygote : <font color=gray><size:12>zcfZygote
+InstanceStorageManager /- vatRoot : <font color=gray><size:12>root
+StartInstance /- InstanceStorageManager : <font color=gray><size:12>root, adminNode, getters
+StartInstance -> vatRoot : startZcf(zoeInstanceAdmin,\ninstanceRecord,\nissuerStorage, privateArgs)
+vatRoot -> ZcfZygote : startContract(zoeInstanceAdmin,\ninstanceRecord,\nissuerStorage, privateArgs)
+ZcfZygote -> ZcfZygote : set up instance state
+ZcfZygote -> contract : start(zcf, privateArgs,...)
+ZcfZygote /- contract : <font color=gray><size:12>publicFacet, creatorFacet, handleOfferObj
+StartInstance /- ZcfZygote : <font color=gray><size:12>publicFacet, creatorFacet, handleOfferObj
+
+note left
+resolve facet & handleOfferObj promises
+end note
+
+@enduml

packages/zoe/docs/ZoeDataInitialization.puml

@@ -0,0 +1,37 @@
+@startuml Zoe/ZCF dataStore initialization
+
+box Zoe startup
+participant bootstrap
+participant Zoe
+participant ZoeStorageManager
+collections InstanceAdminStorage
+participant startInstance
+
+end box
+
+bootstrap -> Zoe: makeZoeKit(...)
+Zoe -> ZoeStorageManager : makeZoeStorageManager()
+ZoeStorageManager -> ZoeStorageManager : provideIssuerStorage()
+ZoeStorageManager -> ZoeStorageManager : makeEscrowStorage()
+ZoeStorageManager -> ZoeStorageManager : vivifyInvitationKit()
+ZoeStorageManager -> InstanceAdminStorage : makeInstanceAdminStorage()
+InstanceAdminStorage -> InstanceAdminStorage : instanceToInstanceAdmin
+ZoeStorageManager /- InstanceAdminStorage : <font color=gray><size:12>getters..., \n<font color=gray><size:12>initInstanceAdmin
+ZoeStorageManager -> ZoeStorageManager : makeInstallationStorage()
+Zoe /-- ZoeStorageManager : <font color=gray><size:12>{makeZoeInstanceStorageManager,\n<font color=gray><size:12>getters, invitationIssuer}
+Zoe -> startInstance : makeStartInstance(makeZoeInstanceStorageManager, <bundle details>, ...)
+Zoe /- startInstance : <font color=gray><size:12>startInstance
+Zoe -> Zoe : makeOfferMethod()
+
+note right
+When Zoe starts up, it initializes datastores that hold data generic to
+all contracts. It creates InstanceAdminStorage which will hold
+instanceAdmins that have data for individual instances.
+startInstance() is used for creating new instances. offer() is used to
+exercise invitations.
+end note
+
+Zoe -> Zoe : makeZoeService(offer)
+Zoe -\ bootstrap : <font color=gray><size:12>ZoeService
+
+@enduml

packages/zoe/docs/offers+invitations+seats.puml

@@ -0,0 +1,56 @@
+@startuml Zoe/ZCF: Invitations, Offers, Seats
+
+actor user
+participant "Zoe\n<size:12>(shared state)" as Zoe
+participant "Zoe\n<size:12>(instance state)" as ZoeInstance
+participant ZCF
+participant contract
+
+== making invitations ==
+
+contract -> ZCF : makeInvitation(handler, desc, ...)
+ZCF -> ZCF : handle = storeOfferHandler(handler)
+ZCF -> Zoe : makeInvitation(handle,desc,...)
+ZCF /- Zoe : <font color=gray><size:12>invitation
+contract /- ZCF : <font color=gray><size:12>invitation
+note bottom
+The invitation might be returned via a public facet,
+or from a method on a seat, or some other way.
+end note
+
+== making an offer ==
+
+user -> Zoe : E(zoe).offer(invitation,\nproposal, payment, ...)
+Zoe -> Zoe : find instance from invitation\nburn invitation\nvalidate acceptingOffers()\nclean proposal\ndeposit Payments
+Zoe -> ZoeInstance : makeUserSeat()
+ZoeInstance -> ZoeInstance :make:\n  offefResultPromiseKit\n  exitObjPromiseKit\n  seatHandle
+ZoeInstance -> ZoeInstance : { userSeat, zoeSeatAdmin } =\n  makeSeatAdminKit(alloc, proposal, promises, ...)
+ZoeInstance -> ZoeInstance : store zoeSeatAdmin
+ZoeInstance -> ZCF : handleOffer(invitation, seatData)
+ZCF -> ZCF : makeZcfSeat()
+ZCF -> contract : handler(zcfSeat, offerArgs)
+contract -> contract : whatever
+ZCF -> ZCF : make offerResultPromiseKit
+ZCF -> ZCF : exitObj = makeExitObj()
+ZoeInstance /- ZCF : <font color=gray><size:12>offerResultPromise, exitObj
+user /- ZoeInstance : <font color=gray><size:12>userSeat
+ZCF /- contract : <font color=gray><size:12>offerResult, exitObj
+ZCF -> ZCF : wait for result, then\n  resolve promise or fail seat
+ZCF -> ZoeInstance : <font color=gray><size:12>promise resolution
+ZoeInstance -> ZoeInstance : resolvePromises or throw()
+
+== creating empty seats ==
+
+contract -> ZCF : makeEmptySeatKit()
+ZCF -> ZCF : promise = makePromiseKit
+ZCF -> ZCF : seatHandle = makeSeatHandle()
+ZCF -> ZCF : makeZcfSeat({}, {}, seatHandle)
+ZCF -> ZCF : exitObj = makeExitObj({}, handle)
+ZCF -> ZoeInstance : makeNoEscrowSeatKit({}, {}, exitObj, seatHandle)
+ZCF -> contract : <font color=gray><size:12>{ zcfSeat, userSeat: promise }
+ZoeInstance -> ZoeInstance : { userSeat, notifier, zoeSeatAdmin } =\n  makeSeatAdminKit(alloc, proposal,\n  promises, ...)
+ZoeInstance -> ZoeInstance : store zoeSeatAdmin
+ZCF /- ZoeInstance : <font color=gray><size:12>useSeat, notifier
+ZCF -> ZCF : <font color=gray>resolve userSeat promise
+
+@enduml