Skip to content

Commit

Permalink
Remove mention of private defpacts from the reference manual (#1207)
Browse files Browse the repository at this point in the history
Co-authored-by: Emily Pillmore <emily@kadena.io>
  • Loading branch information
jwiegley and emilypi authored Apr 27, 2023
1 parent ec9ff8e commit baac04e
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 82 deletions.
34 changes: 6 additions & 28 deletions docs/en/pact-reference.md
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.

### 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
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

0 comments on commit baac04e

Please sign in to comment.