diff --git a/packages/zoe/docs/Invitations,Offers,Seats.png b/packages/zoe/docs/Invitations,Offers,Seats.png new file mode 100644 index 00000000000..531f0a5d0e2 Binary files /dev/null and b/packages/zoe/docs/Invitations,Offers,Seats.png differ diff --git a/packages/zoe/docs/ZcfDataInitialization.puml b/packages/zoe/docs/ZcfDataInitialization.puml new file mode 100644 index 00000000000..87d77dbb60f --- /dev/null +++ b/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 : 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 : start + +vatRoot /- ZcfZygote : zcfZygote +InstanceStorageManager /- vatRoot : root +StartInstance /- InstanceStorageManager : 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 : publicFacet, creatorFacet, handleOfferObj +StartInstance /- ZcfZygote : publicFacet, creatorFacet, handleOfferObj + +note left +resolve facet & handleOfferObj promises +end note + +@enduml diff --git a/packages/zoe/docs/Zoe+ZCF-DataStores.png b/packages/zoe/docs/Zoe+ZCF-DataStores.png new file mode 100644 index 00000000000..1a1b1ee47e5 Binary files /dev/null and b/packages/zoe/docs/Zoe+ZCF-DataStores.png differ diff --git a/packages/zoe/docs/ZoeDataInitialization.puml b/packages/zoe/docs/ZoeDataInitialization.puml new file mode 100644 index 00000000000..daf49660549 --- /dev/null +++ b/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 : getters..., \ninitInstanceAdmin +ZoeStorageManager -> ZoeStorageManager : makeInstallationStorage() +Zoe /-- ZoeStorageManager : {makeZoeInstanceStorageManager,\ngetters, invitationIssuer} +Zoe -> startInstance : makeStartInstance(makeZoeInstanceStorageManager, , ...) +Zoe /- startInstance : 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 : ZoeService + +@enduml \ No newline at end of file diff --git a/packages/zoe/docs/ZoeZCFDataStoreInitialization.png b/packages/zoe/docs/ZoeZCFDataStoreInitialization.png new file mode 100644 index 00000000000..a5551676a98 Binary files /dev/null and b/packages/zoe/docs/ZoeZCFDataStoreInitialization.png differ diff --git a/packages/zoe/docs/ZoeZCFInvitations,Offers,Seats.png b/packages/zoe/docs/ZoeZCFInvitations,Offers,Seats.png new file mode 100644 index 00000000000..531f0a5d0e2 Binary files /dev/null and b/packages/zoe/docs/ZoeZCFInvitations,Offers,Seats.png differ diff --git a/packages/zoe/docs/offers+invitations+seats.puml b/packages/zoe/docs/offers+invitations+seats.puml new file mode 100644 index 00000000000..8f06a946915 --- /dev/null +++ b/packages/zoe/docs/offers+invitations+seats.puml @@ -0,0 +1,56 @@ +@startuml Zoe/ZCF: Invitations, Offers, Seats + +actor user +participant "Zoe\n(shared state)" as Zoe +participant "Zoe\n(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 : invitation +contract /- ZCF : 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 : offerResultPromise, exitObj +user /- ZoeInstance : userSeat +ZCF /- contract : offerResult, exitObj +ZCF -> ZCF : wait for result, then\n resolve promise or fail seat +ZCF -> ZoeInstance : 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 : { zcfSeat, userSeat: promise } +ZoeInstance -> ZoeInstance : { userSeat, notifier, zoeSeatAdmin } =\n makeSeatAdminKit(alloc, proposal,\n promises, ...) +ZoeInstance -> ZoeInstance : store zoeSeatAdmin +ZCF /- ZoeInstance : useSeat, notifier +ZCF -> ZCF : resolve userSeat promise + +@enduml \ No newline at end of file