Skip to content

Commit

Permalink
Document asset related packages (#85)
Browse files Browse the repository at this point in the history
* document asset interfaces

* document asset implementation

* remove bonds and equity from experimental

* add a short explanation to the different packages

* move instrument packages to asset specific extensions
  • Loading branch information
markus-da authored Sep 7, 2022
1 parent f0ff11d commit 591f205
Show file tree
Hide file tree
Showing 18 changed files with 130 additions and 49 deletions.
1 change: 0 additions & 1 deletion docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,6 @@ Daml Finance Documentation
Core Interfaces <packages/core-interfaces>
packages/core-implementations
packages/asset-specific-extensions
packages/experimental-extensions
packages/upgrading

.. toctree::
Expand Down
91 changes: 86 additions & 5 deletions docs/source/packages/asset-specific-extensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,89 @@
Asset-specific Extensions
#########################

- Tokens
- Daml.Finance.Instrument.Base
- Generic
- Daml.Finance.Interface.Instrument.Generic
- Daml.Finance.Instrument.Generic
Tokens
======

- ``Daml.Finance.Interface.Instrument.Base``

This package contains the *interface* for a basic instrument. It contains the following modules:

- :ref:`Factory <module-daml-finance-interface-instrument-base-factory-89800>`: Interface that allows implementing templates to create instruments.
- :ref:`Instrument <module-daml-finance-interface-instrument-base-instrument-57320>`: Base interface for an instrument. This interface does not define any lifecycling logic.

- ``Daml.Finance.Instrument.Base``

This package contains the *implementation* of a basic instrument. It contains the following module:

- :ref:`Instrument <module-daml-finance-instrument-base-instrument-53549>`: Base implementation of an Instrument which does not define any lifecycling logic.

Check out the :doc:`Transfer tutorial <../../tutorial/getting-started/transfer>` for an example on how to create a base instrument and use it for a transfer.

Bonds
=====

- ``Daml.Finance.Interface.Instrument.Bond``

This package contains the *interface* for different bond types, defined in the following modules:

- :ref:`FixedRate <module-daml-finance-interface-instrument-bond-fixedrate-31328>`: Interface that allows implementing templates to create fixed rate bonds.
- :ref:`FloatingRate <module-daml-finance-interface-instrument-bond-floatingrate-5967>`: Interface that allows implementing templates to create floating rate bonds.
- :ref:`InflationLinked <module-daml-finance-interface-instrument-bond-inflationlinked-64713>`: Interface that allows implementing templates to create inflation linked bonds.
- :ref:`ZeroCoupon <module-daml-finance-interface-instrument-bond-zerocoupon-20445>`: Interface that allows implementing templates to create zero coupon bonds.

- ``Daml.Finance.Instrument.Bond``

This package contains the *implementation* of different bond types, defined in the following modules:

- :ref:`FixedRate <module-daml-finance-instrument-bond-fixedrate-44039>`: This template models a fixed rate bond. It pays a fixed coupon rate at the end of every coupon period.
- :ref:`FloatingRate <module-daml-finance-instrument-bond-floatingrate-31782>`: This template models a floating rate bond. It pays a floating coupon rate at the end of every coupon period.
- :ref:`InflationLinked <module-daml-finance-instrument-bond-inflationlinked-38254>`: This template models an inflation linked bond. It pays an inflation adjusted coupon at the end of every coupon period.
- :ref:`ZeroCoupon <module-daml-finance-instrument-bond-zerocoupon-72656>`: This template models a zero coupon bond. It does not pay any coupons, only the redemption amount at maturity.
- :ref:`Util <module-daml-finance-instrument-bond-util-70458>`: Utility functions related to creating Contingent Claims for coupons / redemption and bond lifecycling logic.

Check out the tutorial on :doc:`How to use the Bond extension package <../../tutorial/instrument-modelling/bond-extension>` for a description how to use the bond extension in practice.
There is also the tutorial :doc:`How to implement a Contingent Claims-based instrument <../../tutorial/instrument-modelling/contingent-claims-instrument>`, which describes how the claims are defined and how the lifecycle interface is implemented for bonds.

Equity
======

- ``Daml.Finance.Interface.Instrument.Equity``

This package contains the *interface* for equities. It has the following modules:

- :ref:`Factory <module-daml-finance-interface-instrument-equity-factory-97140>`: Interface that allows implementing templates to create equity instruments.
- :ref:`Instrument <module-daml-finance-interface-instrument-equity-instrument-13224>`: Interface for a generic equity instrument.

- ``Daml.Finance.Instrument.Equity``

This package contains the *implementation* for equities. It has the following modules:

- :ref:`Factory <module-daml-finance-instrument-equity-factory-96899>`: Factory template for instrument creation.
- :ref:`Instrument <module-daml-finance-instrument-equity-instrument-69265>`: Instrument representing a common stock.

For a detailed explanation of the equity extension, check out the ``src/test/daml/Daml/Finance/Instrument/Equity/Test`` folder. It demonstrates how to originate an equity instrument,
how to create and lifecycle a cash dividend, and how to handle corporate actions like mergers and stock splits.

Generic
=======

- ``Daml.Finance.Interface.Instrument.Generic``

This package contains the *interface* and types required for generic instruments using ``Contingent Claims``, including lifecycling logic. It contains the following modules:

- :ref:`Util.Claims.Lifecycle <module-daml-finance-interface-instrument-generic-util-claims-lifecycle-66560>`: Defines different types of events and how to lifecycle them.
- :ref:`Util.Claims <module-daml-finance-interface-instrument-generic-util-claims-70604>`: Contains utility functions for claims, e.g. checking content of a claim and converting claim time.
- :ref:`Election <module-daml-finance-interface-instrument-generic-election-94835>`: Interface implemented by templates that represents a (claim-based) election.
- :ref:`Factory <module-daml-finance-interface-instrument-generic-factory-11761>`: Interface that allows implementing templates to create generic instruments.
- :ref:`HasClaims <module-daml-finance-interface-instrument-generic-hasclaims-47920>`: Interface implemented by templates that can be represented as a set of contingent claims.
- :ref:`Types <module-daml-finance-interface-instrument-generic-types-37112>`: Types related to claims and what is require to represent claims (e.g. Deliverable and Observable.)

- ``Daml.Finance.Instrument.Generic``

This package contains the *implementation* and types required for generic instruments, including lifecycling logic. It contains the following modules:

- :ref:`Election <module-daml-finance-instrument-generic-election-56972>`: Implementation of Election (e.g. the exercise of an option) and ElectionFactory (to delegate the right to create Elections).
- :ref:`Factory <module-daml-finance-instrument-generic-factory-42712>`: Factory template for generic instrument creation.
- :ref:`Instrument <module-daml-finance-instrument-generic-instrument-67364>`: An instrument representing a generic payoff, modelled using ``Contingent Claims``.

The tutorial :doc:`How to use the Derivative extension to model generic instruments <../../tutorial/instrument-modelling/derivative-extension>` describes how a payoff is defined using ``Contingent Claims`` in practice.
17 changes: 13 additions & 4 deletions docs/source/packages/core-implementations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,19 @@
Core Implementations
####################

- Daml.Finance.Asset
- Holding (signatory model, implementations)
- Account
- Factories
- ``Daml.Finance.Holding``

This package contains the *implementation* and utility functions for holdings and accounts. It has the following modules:

- :ref:`Account <module-daml-finance-holding-account-88149>`: A relationship between a custodian and an asset owner. It is referenced by holdings.
- :ref:`Fungible <module-daml-finance-holding-fungible-7201>`: Implementation of a fungible holding, including split and merge functionality.
- :ref:`NonFungible <module-daml-finance-holding-nonfungible-86571>`: Implementation of a non-fungible holding, which cannot be split or merged.
- :ref:`NonTransferable <module-daml-finance-holding-nontransferable-44402>`: Implementation of a non-transferable holding.
- :ref:`Util <module-daml-finance-holding-util-87323>`: Utility functions related to holdings, e.g. locking a holding.

The :doc:`Core Concepts <../core-concepts>` page explains the relationship between instruments, holdings and accounts.
Check out the :doc:`Transfer tutorial <../../tutorial/getting-started/transfer>` for a description on how to create a holding on an instrument and how to transfer it between accounts.

- Daml.Finance.Settlement
- Batch
- Instruction
Expand Down
21 changes: 16 additions & 5 deletions docs/source/packages/core-interfaces.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,22 @@
Core Interfaces
###############

- Daml.Finance.Interface.Asset
- Holding (purpose, roles, functionality)
- Account (^ + keying)
- Instrument (^ + keying)
- Factories (^ + visibility)
- ``Daml.Finance.Interface.Holding``

This package contains the *interface* and utility functions for holdings and accounts. It has the following modules:

- :ref:`Factory.Account <module-daml-finance-interface-holding-factory-account-66430>`: Interface that allows implementing templates to create accounts.
- :ref:`Factory.Holding <module-daml-finance-interface-holding-factory-holding-2450>`: Holding factory contract used to create (credit) and archive (debit) holdings.
- :ref:`Account <module-daml-finance-interface-holding-account-93234>`: Interface which represents an established relationship between a provider and an owner.
- :ref:`Base <module-daml-finance-interface-holding-base-24195>`: Base interface for a holding.
- :ref:`Fungible <module-daml-finance-interface-holding-fungible-63712>`: Interface for a fungible holding, which allows splitting and merging.
- :ref:`Lockable <module-daml-finance-interface-holding-lockable-23737>`: An interface respresenting contracts which allow a set of parties to restrict certain actions on a contract.
- :ref:`Transferable <module-daml-finance-interface-holding-transferable-88121>`: Interface respresenting a contract where ownership can be transferred to other parties.
- :ref:`Util <module-daml-finance-interface-holding-util-81618>`: Utility functions related to holdings, e.g. getting the account / instrument / owner of a holding.

The :doc:`Core Concepts <../core-concepts>` page explains the relationship between instruments, holdings and accounts.
Check out the :doc:`Transfer tutorial <../../tutorial/getting-started/transfer>` for a description on how to create a holding on an instrument and how to transfer it between accounts.

- Daml.Finance.Interface.Settlement
- Instruction
- Settleable (-> rename to Settlement / Batch?)
Expand Down
19 changes: 0 additions & 19 deletions docs/source/packages/experimental-extensions.rst

This file was deleted.

2 changes: 1 addition & 1 deletion src/main/daml/Daml/Finance/Instrument/Base/Instrument.daml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import Daml.Finance.Interface.Util.Disclosure qualified as Disclosure (I, SetObs
type T = Instrument

instance Instrument.HasImplementation T
-- | Base implementation for Instrument which does not define any lifecycling logic.
-- | Base implementation of an Instrument which does not define any lifecycling logic.
template Instrument
with
depository : Party
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ type T = Instrument
instance Instrument.HasImplementation T

-- | This template models an inflation linked bond.
-- It pays a fixed coupon rate at the end of every coupon period.
-- This is calculated based on a principal that is adjusted according to an inflation index, for example the Consumer Price Index (CPI) in the U.S.
-- It pays an inflation adjusted coupon at the end of every coupon period.
-- The coupon is based on a fixed rate, which is applied to a principal that is adjusted according to an inflation index, for example the Consumer Price Index (CPI) in the U.S.
-- For example: 0.5% p.a. coupon, CPI adjusted principal:
-- At maturity, the greater of the adjusted principal and the original principal is redeemed.
-- For clarity, this only applies to the redemption amount. The coupons are always calculated based on the adjusted principal.
Expand Down
2 changes: 1 addition & 1 deletion src/main/daml/Daml/Finance/Instrument/Generic/Factory.daml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import Daml.Finance.Interface.Util.Disclosure qualified as Disclosure (I, SetObs
type F = Factory

instance GenericFactory.HasImplementation Factory
-- | Factory template for instrument creation.
-- | Factory template for generic instrument creation.
template Factory
with
provider : Party
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ type T = Instrument
instance Instrument.HasImplementation T
instance Election.ExercisableHasImplementation T

-- | An instrument representing a generic derivative, modelled using the Contingent Claims library.
-- | An instrument representing a generic payoff, modelled using the Contingent Claims library.
-- The responsibility for processing lifecycle events as well as elections is delegated to the issuer, who is hence responsible for providing the correct `Observable`\s.
template Instrument
with
Expand Down
4 changes: 2 additions & 2 deletions src/main/daml/Daml/Finance/Interface/Holding/Lockable.daml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ instance HasImplementation I
instance HasToInterface I Base.I where _toInterface = asHolding
instance HasToInterface I Disclosure.I where _toInterface = Base.asDisclosure . asHolding

-- | An interface respresenting contracts which can restrict a contract by a set of specifed parties
-- | An interface respresenting contracts which allow a set of parties to restrict certain actions on a contract.
interface Lockable where
viewtype V

Expand All @@ -74,7 +74,7 @@ interface Lockable where
-- ^ Lock a contract.
with
newLocker : Parties
-- ^ Parties which restrain the contracts ability to preform specified actions.
-- ^ Parties which restrain the contract's ability to perform specified actions.
context : Text
-- ^ Reason for acquiring a lock.
lockType : LockType
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ type V = View
-- | View for `Transferable`.
data View = View {} deriving (Eq, Ord, Show)

-- | An interface respresenting a contract where ownership can be transfered to other parties
-- | An interface respresenting a contract where ownership can be transferred to other parties.
interface Transferable where
viewtype View

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create fixed rate bonds.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create floating rate bonds.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create inflation linked bonds.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create zero coupon bonds.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create equity instruments.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ data View = View
-- ^ The provider of the `Factory`.
deriving (Eq, Ord, Show)

-- | Interface that allows implementing templates to create instruments.
-- | Interface that allows implementing templates to create generic instruments.
interface Factory where
viewtype V

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ data View = View
-- ^ The claim's acquisition time.
deriving (Eq, Ord, Show)

-- | Interface implemented by templates that admit a representation as a set of contingent claims.
-- | Interface implemented by templates that can be represented as a set of contingent claims.
interface HasClaims where
viewtype V

Expand Down

0 comments on commit 591f205

Please sign in to comment.