mirror of
https://github.com/corda/corda.git
synced 2024-12-21 05:53:23 +00:00
Docs: address more review comments, add mention of some new features.
This commit is contained in:
Mike Hearn
parent
fb89ab3151
commit
4f9a4a2c2b
@ -1,11 +1,6 @@
|
||||
API: Identity
|
||||
=============
|
||||
|
||||
.. note:: Before reading this page, you should be familiar with the key concepts of :doc:`key-concepts-identity`.
|
||||
|
||||
.. warning:: The ``confidential-identities`` module is still not stabilised, so this API may change in future releases.
|
||||
See :doc:`corda-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
Party
|
||||
@ -37,8 +32,14 @@ basis.
|
||||
The ``PartyAndCertificate`` class is also used by the network map service to represent well-known identities, with the
|
||||
certificate path proving the certificate was issued by the doorman service.
|
||||
|
||||
.. _confidential_identities_ref:
|
||||
|
||||
Confidential identities
|
||||
-----------------------
|
||||
|
||||
.. warning:: The ``confidential-identities`` module is still not stabilised, so this API may change in future releases.
|
||||
See :doc:`corda-api`.
|
||||
|
||||
Confidential identities are key pairs where the corresponding X.509 certificate (and path) are not made public, so that
|
||||
parties who are not involved in the transaction cannot identify the owner. They are owned by a well-known identity,
|
||||
which must sign the X.509 certificate. Before constructing a new transaction the involved parties must generate and
|
||||
|
||||
@ -103,7 +103,7 @@ another transaction.
|
||||
FungibleState
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
`FungibleState<T>` is an interface to represent things which are fungible, this means that there is an expectation that
|
||||
``FungibleState<T>`` is an interface to represent things which are fungible, this means that there is an expectation that
|
||||
these things can be split and merged. That's the only assumption made by this interface. This interface should be
|
||||
implemented if you want to represent fractional ownership in a thing, or if you have many things. Examples:
|
||||
|
||||
@ -120,16 +120,17 @@ The interface is defined as follows:
|
||||
:start-after: DOCSTART 1
|
||||
:end-before: DOCEND 1
|
||||
|
||||
As seen, the interface takes a type parameter `T` that represents the fungible thing in question. This should describe
|
||||
As seen, the interface takes a type parameter ``T`` that represents the fungible thing in question. This should describe
|
||||
the basic type of the asset e.g. GBP, USD, oil, shares in company <X>, etc. and any additional metadata (issuer, grade,
|
||||
class, etc.). An upper-bound is not specified for `T` to ensure flexibility. Typically, a class would be provided that
|
||||
implements `TokenizableAssetInfo` so the thing can be easily added and subtracted using the `Amount` class.
|
||||
class, etc.). An upper-bound is not specified for ``T`` to ensure flexibility. Typically, a class would be provided that
|
||||
implements `TokenizableAssetInfo` so the thing can be easily added and subtracted using the ``Amount`` class.
|
||||
|
||||
This interface has been added in addition to `FungibleAsset` to provide some additional flexibility which
|
||||
`FungibleAsset` lacks, in particular:
|
||||
* `FungibleAsset` defines an amount property of type Amount<Issued<T>>, therefore there is an assumption that all
|
||||
This interface has been added in addition to ``FungibleAsset`` to provide some additional flexibility which
|
||||
``FungibleAsset`` lacks, in particular:
|
||||
|
||||
* ``FungibleAsset`` defines an amount property of type ``Amount<Issued<T>>``, therefore there is an assumption that all
|
||||
fungible things are issued by a single well known party but this is not always the case.
|
||||
* `FungibleAsset` implements `OwnableState`, as such there is an assumption that all fungible things are ownable.
|
||||
* ``FungibleAsset`` implements ``OwnableState``, as such there is an assumption that all fungible things are ownable.
|
||||
|
||||
Other interfaces
|
||||
^^^^^^^^^^^^^^^^
|
||||
@ -170,10 +171,10 @@ When a ``ContractState`` is added to a ``TransactionBuilder``, it is wrapped in
|
||||
|
||||
.. container:: codeset
|
||||
|
||||
.. literalinclude:: ../../core/src/main/kotlin/net/corda/core/contracts/TransactionState.kt
|
||||
:language: kotlin
|
||||
:start-after: DOCSTART 1
|
||||
:end-before: DOCEND 1
|
||||
.. literalinclude:: ../../core/src/main/kotlin/net/corda/core/contracts/TransactionState.kt
|
||||
:language: kotlin
|
||||
:start-after: DOCSTART 1
|
||||
:end-before: DOCEND 1
|
||||
|
||||
Where:
|
||||
|
||||
@ -184,6 +185,8 @@ Where:
|
||||
state
|
||||
* ``constraint`` is a constraint on which contract-code attachments can be used with this state
|
||||
|
||||
.. _reference_states:
|
||||
|
||||
Reference States
|
||||
----------------
|
||||
|
||||
@ -220,11 +223,13 @@ reference states with two different notaries cannot be committed to the ledger.
|
||||
As such, if reference states assigned to multiple different notaries are added to a transaction builder
|
||||
then the check below will fail.
|
||||
|
||||
.. warning:: Currently, encumbrances should not be used with reference states. In the case where a state is
|
||||
encumbered by an encumbrance state, the encumbrance state should also be referenced in the same
|
||||
transaction that references the encumbered state. This is because the data contained within the
|
||||
encumbered state may take on a different meaning, and likely would do, once the encumbrance state
|
||||
is taken into account.
|
||||
.. warning:: Currently, encumbrances should not be used with reference states. In the case where a state is
|
||||
encumbered by an encumbrance state, the encumbrance state should also be referenced in the same
|
||||
transaction that references the encumbered state. This is because the data contained within the
|
||||
encumbered state may take on a different meaning, and likely would do, once the encumbrance state
|
||||
is taken into account.
|
||||
|
||||
.. _state_pointers:
|
||||
|
||||
State Pointers
|
||||
--------------
|
||||
@ -235,12 +240,12 @@ a look-up. There are two types of pointers; linear and static.
|
||||
|
||||
1. ``StaticPointer`` s are for use with any type of ``ContractState``. The ``StaticPointer`` does as it suggests, it always
|
||||
points to the same ``ContractState``.
|
||||
2. The ``LinearPointer`` is for use with ``LinearState`` s. They are particularly useful because due to the way ``LinearState`` s
|
||||
work, the pointer will automatically point you to the latest version of a ``LinearState`` that the node performing ``resolve``
|
||||
is aware of. In effect, the pointer "moves" as the ``LinearState`` is updated.
|
||||
2. The ``LinearPointer`` is for use with LinearStates. They are particularly useful because due to the way LinearStates
|
||||
work, the pointer will automatically point you to the latest version of a LinearState that the node performing ``resolve``
|
||||
is aware of. In effect, the pointer "moves" as the LinearState is updated.
|
||||
|
||||
``StatePointer`` s do not enable a feature in Corda which was unavailable before. Rather, they help to formalise a pattern
|
||||
which was already possible. In that light it is worth nothing some issues which you may encounter with `StatePointer` s:
|
||||
StatePointers do not enable a feature in Corda which was unavailable before. Rather, they help to formalise a pattern which was
|
||||
already possible. In that light it is worth nothing some issues which you may encounter with it:
|
||||
|
||||
* If the node calling ``resolve`` has not seen any transactions containing a ``ContractState`` which the ``StatePointer``
|
||||
points to, then ``resolve`` will throw an exception. Here, the node calling ``resolve`` might be missing some crucial data.
|
||||
@ -248,7 +253,7 @@ a look-up. There are two types of pointers; linear and static.
|
||||
the specified ``linearId``. However, there is no guarantee the ``StateAndRef<T>`` returned by ``resolve`` is the most recent
|
||||
version of the ``LinearState``. The node only returns the most recent version that _it_ is aware of.
|
||||
|
||||
**Resolving state pointers in `TransactionBuilder`**
|
||||
**Resolving state pointers in TransactionBuilder**
|
||||
|
||||
When building transactions, any ``StatePointer`` s contained within inputs or outputs added to a ``TransactionBuilder`` can
|
||||
be optionally resolved to reference states using the ``resolveStatePointers`` method. The effect is that the pointed to
|
||||
|
||||
@ -160,7 +160,7 @@ This is no longer necessary with ``ReceiveFinalityFlow`` and the call to ``waitF
|
||||
Step 4. Upgrade your use of SwapIdentitiesFlow
|
||||
----------------------------------------------
|
||||
|
||||
The ``confidential-identities`` module is experimental in Corda 3 and remains so in Corda 4. In this release, the ``SwapIdentitiesFlow``
|
||||
The :ref:`confidential_identities_ref` API is experimental in Corda 3 and remains so in Corda 4. In this release, the ``SwapIdentitiesFlow``
|
||||
has been adjusted in the same way as ``FinalityFlow`` above, to close problems with confidential identities being injectable into a node
|
||||
outside of other flow context. Old code will still work, but it is recommended to adjust your call sites so a session is passed into
|
||||
the ``SwapIdentitiesFlow``.
|
||||
@ -173,6 +173,24 @@ Use a ``MockNetworkConfigOverrides`` object instead. This is an API change we re
|
||||
large amounts of the node internal code through this one API entry point. We have now insulated the test API from node internals and
|
||||
reduced the exposure.
|
||||
|
||||
If you are constructing a MockServices for testing contracts, and your contract uses the Cash contract from the finance app, you
|
||||
now need to explicitly add ``net.corda.finance.contracts`` to the list of ``cordappPackages``. This is a part of the work to disentangle
|
||||
the finance app (which is really a demo app) from the Corda internals. Example::
|
||||
|
||||
val ledgerServices = MockServices(
|
||||
listOf("net.corda.examples.obligation", "net.corda.testing.contracts"),
|
||||
identityService = makeTestIdentityService(),
|
||||
initialIdentity = TestIdentity(CordaX500Name("TestIdentity", "", "GB"))
|
||||
)
|
||||
|
||||
becomes::
|
||||
|
||||
val ledgerServices = MockServices(
|
||||
listOf("net.corda.examples.obligation", "net.corda.testing.contracts", "net.corda.finance.contracts"),
|
||||
identityService = makeTestIdentityService(),
|
||||
initialIdentity = TestIdentity(CordaX500Name("TestIdentity", "", "GB"))
|
||||
)
|
||||
|
||||
Step 6. Security: refactor to avoid violating sealed packages
|
||||
-------------------------------------------------------------
|
||||
|
||||
@ -229,3 +247,12 @@ that causes transaction details to be converted to a PDF and sent to a particula
|
||||
into shared business logic, but it makes perfect sense to put into a user-specific app they developed themselves.
|
||||
|
||||
If your flows could benefit from being extended in this way, read ":doc:`flow-overriding`" to learn more.
|
||||
|
||||
Step 10. Explore other new features that may be useful
|
||||
------------------------------------------------------
|
||||
|
||||
Corda 4 adds several new APIs that help you build applications. Why not explore:
|
||||
|
||||
* The `new withEntityManager API <api/javadoc/net/corda/core/node/ServiceHub.html#withEntityManager-block->`_ for using JPA inside your flows and services.
|
||||
* :ref:`reference_states`, that let you use an input state without consuming it.
|
||||
* :ref:`state_pointers`, that make it easier to 'point' to one state from another and follow the latest version of a linear state.
|
||||
Loading…
Reference in New Issue
Block a user