Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove mention of private defpacts from the reference manual #1207

Merged
merged 2 commits into from
Apr 27, 2023
Merged

Remove mention of private defpacts from the reference manual #1207

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c2b9667
Remove mention of private defpacts from the reference manual
jwiegley Apr 26, 2023
d7ab40b
Update docs/en/pact-reference.md
jwiegley Apr 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 6 additions & 28 deletions docs/en/pact-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1530,42 +1530,22 @@ To share new values
with subsequent steps, a step can [yield](pact-functions.html#yield) values which the subsequent step can recover using
the special [resume](pact-functions.html#resume) binding form.

Pacts are designed to run in one of two different contexts, private and public. A private pact is
indicated by each step identifying a single entity to execute the step, while public steps do
not have entity indicators. A pact can only be uniformly public or private: if some steps
has entity indicators and others do not, this results in an error at load time.

### Public Pacts
Public pacts are comprised of steps that can only execute in strict sequence. Any enforcement of who can execute a step
Pacts are comprised of steps that can only execute in strict sequence. Any enforcement of who can execute a step
happens within the code of the step expression. All steps are "manually" initiated by some participant
in the transaction with CONTINUATION commands sent into the blockchain.

### Private Pacts
Private pacts are comprised of steps that execute in sequence where each step only executes on entity
nodes as selected by the provided 'entity' argument in the step; other entity nodes "skip" the step.
Private pacts are executed automatically by the blockchain platform after the initial step is sent
in, with the executing entity's node automatically sending the CONTINUATION command for the next step.

### Failures, Rollbacks and Cancels

Failure handling is dramatically different in public and private pacts.

In public pacts, a rollback expression is specified to indicate that the pact can be "cancelled" at
In pacts, a rollback expression is specified to indicate that the pact can be "cancelled" at
this step with a participant sending in a CANCEL message before the next step is executed. Once the last
step of a pact has been executed, the pact will be finished and cannot be rolled back. Failures
in public steps are no different than a failure in a non-pact transaction: all changes are rolled back.
Pacts can therefore only be canceled explicitly and should be modeled to offer all necessary cancel options.

In private pacts, the sequential execution of steps is automated by the blockchain platform itself. A failure
results in a ROLLBACK message being sent from the executing entity node which will trigger any rollback expression
specified in the previous step, to be executed by that step's entity. This failure will then "cascade" to the
previous step as a new ROLLBACK transaction, completing when the first step is rolled back.

### Yield and Resume

A step can yield values to the following step using [yield](pact-functions.html#yield) and [resume](pact-functions.html#resume). In public,
this is an unforgeable value, as it is maintained within the blockchain pact scope. In private, this is
simply a value sent with a RESUME message from the executed entity.
A step can yield values to the following step using [yield](pact-functions.html#yield) and [resume](pact-functions.html#resume).
This is an unforgeable value, as it is maintained within the blockchain pact scope.
jwiegley marked this conversation as resolved.
Show resolved Hide resolved

### Pact execution scope and `pact-id`

Expand Down Expand Up @@ -1954,9 +1934,7 @@ Define NAME as VALUE, with option DOC-OR-META. Value is evaluated upon module lo
Define NAME as a _pact_, a computation comprised of multiple steps that occur
in distinct transactions.
Identical to [defun](#defun) except body must be comprised of [steps](#step) to be
executed in strict sequential order. Steps must uniformly be "public" (no entity indicator)
or "private" (with entity indicator). With private steps, failures result in a reverse-sequence
"rollback cascade".
executed in strict sequential order.

```lisp
(defpact payment (payer payer-entity payee
Expand All @@ -1968,7 +1946,7 @@ or "private" (with entity indicator). With private steps, failures result in a r
(credit payee amount)))
```

Public defpacts may be nested (though the recursion restrictions apply, so it must be a different defpact). They may be kicked off
Defpacts may be nested (though the recursion restrictions apply, so it must be a different defpact). They may be executed
like a regular function call within a defpact, but are continued after the first step by calling `continue` with the same arguments.

As such, they have the following restrictions:
Expand Down
73 changes: 19 additions & 54 deletions docs/en/pact-reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1993,63 +1993,30 @@ subsequent steps. To share new values with subsequent steps, a step can
can recover using the special `resume <pact-functions.html#resume>`__
binding form.

Pacts are designed to run in one of two different contexts, private and
public. A private pact is indicated by each step identifying a single
entity to execute the step, while public steps do not have entity
indicators. A pact can only be uniformly public or private: if some
steps has entity indicators and others do not, this results in an error
at load time.

Public Pacts
~~~~~~~~~~~~

Public pacts are comprised of steps that can only execute in strict
sequence. Any enforcement of who can execute a step happens within the
code of the step expression. All steps are “manually” initiated by some
participant in the transaction with CONTINUATION commands sent into the
blockchain.

Private Pacts
~~~~~~~~~~~~~

Private pacts are comprised of steps that execute in sequence where each
step only executes on entity nodes as selected by the provided ‘entity’
argument in the step; other entity nodes “skip” the step. Private pacts
are executed automatically by the blockchain platform after the initial
step is sent in, with the executing entity’s node automatically sending
the CONTINUATION command for the next step.
Pacts are comprised of steps that can only execute in strict sequence.
Any enforcement of who can execute a step happens within the code of the
step expression. All steps are “manually” initiated by some participant
in the transaction with CONTINUATION commands sent into the blockchain.

Failures, Rollbacks and Cancels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Failure handling is dramatically different in public and private pacts.

In public pacts, a rollback expression is specified to indicate that the
pact can be “cancelled” at this step with a participant sending in a
CANCEL message before the next step is executed. Once the last step of a
pact has been executed, the pact will be finished and cannot be rolled
back. Failures in public steps are no different than a failure in a
non-pact transaction: all changes are rolled back. Pacts can therefore
only be canceled explicitly and should be modeled to offer all necessary
cancel options.

In private pacts, the sequential execution of steps is automated by the
blockchain platform itself. A failure results in a ROLLBACK message
being sent from the executing entity node which will trigger any
rollback expression specified in the previous step, to be executed by
that step’s entity. This failure will then “cascade” to the previous
step as a new ROLLBACK transaction, completing when the first step is
rolled back.
In pacts, a rollback expression is specified to indicate that the pact
can be “cancelled” at this step with a participant sending in a CANCEL
message before the next step is executed. Once the last step of a pact
has been executed, the pact will be finished and cannot be rolled back.
Failures in public steps are no different than a failure in a non-pact
transaction: all changes are rolled back. Pacts can therefore only be
canceled explicitly and should be modeled to offer all necessary cancel
options.

Yield and Resume
~~~~~~~~~~~~~~~~

A step can yield values to the following step using
`yield <pact-functions.html#yield>`__ and
`resume <pact-functions.html#resume>`__. In public, this is an
unforgeable value, as it is maintained within the blockchain pact scope.
In private, this is simply a value sent with a RESUME message from the
executed entity.
`resume <pact-functions.html#resume>`__. This is an unforgeable value,
as it is maintained within the blockchain pact scope.

Pact execution scope and ``pact-id``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -2513,9 +2480,7 @@ defpact
Define NAME as a *pact*, a computation comprised of multiple steps that
occur in distinct transactions. Identical to `defun <#defun>`__ except
body must be comprised of `steps <#step>`__ to be executed in strict
sequential order. Steps must uniformly be “public” (no entity indicator)
or “private” (with entity indicator). With private steps, failures
result in a reverse-sequence “rollback cascade”.
sequential order.

.. code:: lisp

Expand All @@ -2527,10 +2492,10 @@ result in a reverse-sequence “rollback cascade”.
(step payee-entity
(credit payee amount)))

Public defpacts may be nested (though the recursion restrictions apply,
so it must be a different defpact). They may be kicked off like a
regular function call within a defpact, but are continued after the
first step by calling ``continue`` with the same arguments.
Defpacts may be nested (though the recursion restrictions apply, so it
must be a different defpact). They may be kicked off like a regular
function call within a defpact, but are continued after the first step
by calling ``continue`` with the same arguments.

As such, they have the following restrictions: - The number of steps of
the child must match the number of steps of the parent. - If a parent
Expand Down