ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-18 02:39:51 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

got rid of a lot of the long errors in the markdown docs

Browse Source
This commit is contained in:
ben 2019-03-25 17:14:58 +00:00 committed by Mike Hearn
parent ed94387eff
commit 8d44eabf4a
5 changed files with 31 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/design/data-model-upgrades/migrate-to-signature-constraint.md
View File

@ -69,7 +69,7 @@ A normal node would just download the signed jar using the normal process for th
### Caveats ### Caveats
###### Someone really wants to issue states with the HashConstraint, and ensure that can never change. #### Someone really wants to issue states with the HashConstraint, and ensure that can never change.
- As mentioned above the transaction builder could only automatically transition states created pre-v4. - As mentioned above the transaction builder could only automatically transition states created pre-v4.
@ -80,7 +80,7 @@ A normal node would just download the signed jar using the normal process for th
The option in this case is to force such parties to actually create a new contract (maybe subclass the version they want), own it, and hardcode the check as above. The option in this case is to force such parties to actually create a new contract (maybe subclass the version they want), own it, and hardcode the check as above.
###### Some nodes haven't upgraded all their states by the time a new release is already being used on the network. #### Some nodes haven't upgraded all their states by the time a new release is already being used on the network.
- A transaction mixing an original HashConstraint state, and a v2 Signature constraint state will not pass. The only way out is to strongly "encourage" nodes to upgrade before the new release. - A transaction mixing an original HashConstraint state, and a v2 Signature constraint state will not pass. The only way out is to strongly "encourage" nodes to upgrade before the new release.

4
docs/source/design/linear-pointer/design.md
View File

@ -73,7 +73,7 @@ class LinearPointer(override val pointer: UniqueIdentifier) : StatePointer {
} }
``` ```
#### Bi-directional link ### Bi-directional link
Symmetrical relationships can be modelled by embedding a `LinearPointer` in the pointed-to `LinearState` which points in the "opposite" direction. **Note:** this can only work if both states are `LinearState`s. Symmetrical relationships can be modelled by embedding a `LinearPointer` in the pointed-to `LinearState` which points in the "opposite" direction. **Note:** this can only work if both states are `LinearState`s.
@ -81,7 +81,7 @@ Symmetrical relationships can be modelled by embedding a `LinearPointer` in the
It is important to note that this design only standardises a pattern which is currently possible with the platform. In other words, this design does not enable anything new. It is important to note that this design only standardises a pattern which is currently possible with the platform. In other words, this design does not enable anything new.
#### Tokens ### Tokens
Uncoupling token type definitions from the notion of ownership. Using the `LinearPointer`, `Token` states can include an `Amount` of some pointed-to type. The pointed-to type can evolve independently from the `Token` state which should just be concerned with the question of ownership. Uncoupling token type definitions from the notion of ownership. Using the `LinearPointer`, `Token` states can include an `Amount` of some pointed-to type. The pointed-to type can evolve independently from the `Token` state which should just be concerned with the question of ownership.

25
docs/source/design/monitoring-management/design.md
View File

@ -113,7 +113,7 @@ Expanding on the first goal identified above, the following requirements have be
Audit data should include sufficient contextual information to enable optimal off-line analysis. Audit data should include sufficient contextual information to enable optimal off-line analysis.
Auditing should apply to all Corda node processes (running CorDapps, notaries, oracles). Auditing should apply to all Corda node processes (running CorDapps, notaries, oracles).
#### Use Cases ### Use Cases
It is envisaged that operational management and support teams will use the metrics and information collated from this It is envisaged that operational management and support teams will use the metrics and information collated from this
design, either directly or through an integrated enterprise-wide systems management platform, to perform the following: design, either directly or through an integrated enterprise-wide systems management platform, to perform the following:
@ -177,7 +177,7 @@ There are a number of activities and parts to the solution proposal:
queue), and exposes key metrics using JMX (using role-based authentication using Artemis's JAAS plug-in support to queue), and exposes key metrics using JMX (using role-based authentication using Artemis's JAAS plug-in support to
ensure Artemis cannot be controlled via JMX).. ensure Artemis cannot be controlled via JMX)..
##### Restrictions ### Restrictions
As of Corda M11, Java serialisation in the Corda node has been restricted, meaning MBeans access via the JMX port will no longer work. As of Corda M11, Java serialisation in the Corda node has been restricted, meaning MBeans access via the JMX port will no longer work.
@ -200,7 +200,7 @@ include:
| [Collectd](https://collectd.org/) | OS | Collector agent (written in C circa 2005). Data acquisition and storage handled by over 90 plugins. | | [Collectd](https://collectd.org/) | OS | Collector agent (written in C circa 2005). Data acquisition and storage handled by over 90 plugins. |
| [Telegraf](https://github.com/influxdata/telegraf) | OS | Collector agent (written in Go, active community) | | [Telegraf](https://github.com/influxdata/telegraf) | OS | Collector agent (written in Go, active community) |
| [Graphite](https://graphiteapp.org/) | OS | Monitoring tool that stores, retrieves, shares, and visualizes time-series data. | | [Graphite](https://graphiteapp.org/) | OS | Monitoring tool that stores, retrieves, shares, and visualizes time-series data. |
| [StatsD](https://github.com/etsy/statsd) | OS | Collector daemon that runs on the [Node.js](http://nodejs.org/) platform and listens for statistics, like counters and timers, sent over [UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) or [TCP](http://en.wikipedia.org/wiki/Transmission_Control_Protocol) and sends aggregates to one or more pluggable backend services (e.g., [Graphite](http://graphite.readthedocs.org/)). | | [StatsD](https://github.com/etsy/statsd) | OS | Collector daemon that runs on the [Node.js](http://nodejs.org/) platform and listens for statistics, like counters and timers, sent over [UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) or [TCP](http://en.wikipedia.org/wiki/Transmission_Control_Protocol) and sends aggregates to one or more pluggable backend services (e.g., Graphite). |
| [fluentd](https://www.fluentd.org/) | OS | Collector daemon which collects data directly from logs and databases. Often used to analyze event logs, application logs, and clickstreams (a series of mouse clicks). | | [fluentd](https://www.fluentd.org/) | OS | Collector daemon which collects data directly from logs and databases. Often used to analyze event logs, application logs, and clickstreams (a series of mouse clicks). |
| [Prometheus](https://prometheus.io/) | OS | End to end monitoring solution using time-series data (eg. metric name and a set of key-value pairs) and includes collection, storage, query and visualization. | | [Prometheus](https://prometheus.io/) | OS | End to end monitoring solution using time-series data (eg. metric name and a set of key-value pairs) and includes collection, storage, query and visualization. |
| [NewRelic](https://newrelic.com/) | £ | Full stack instrumentation for application monitoring and real-time analytics solution. | | [NewRelic](https://newrelic.com/) | £ | Full stack instrumentation for application monitoring and real-time analytics solution. |
@ -446,7 +446,6 @@ Primary node services exposed publicly via ServiceHub (SH) or internally by Serv
| CordaPersistence | SHI | CordaPersistence | INFO coverage within `HibernateConfiguration` | | CordaPersistence | SHI | CordaPersistence | INFO coverage within `HibernateConfiguration` |
| CordappProviderInternal | SHI | CordappProviderImpl | none | | CordappProviderInternal | SHI | CordappProviderImpl | none |
| VaultServiceInternal | SHI | NodeVaultService | see SH | | VaultServiceInternal | SHI | NodeVaultService | see SH |
| | | | |
Corda subsystem components: Corda subsystem components:
@ -458,7 +457,6 @@ Corda subsystem components:
| NotaryService | RaftNonValidatingNotaryService | as above | | NotaryService | RaftNonValidatingNotaryService | as above |
| NotaryService | BFTNonValidatingNotaryService | Logging coverage (info, debug) | | NotaryService | BFTNonValidatingNotaryService | Logging coverage (info, debug) |
| Doorman | DoormanServer (Enterprise only) | Some logging (info, warn, error), and use of `println` | | Doorman | DoormanServer (Enterprise only) | Some logging (info, warn, error), and use of `println` |
| | | |
Corda core flows: Corda core flows:
@ -467,19 +465,18 @@ Corda core flows:
| FinalityFlow | none | NotaryException | NOTARISING, BROADCASTING | | FinalityFlow | none | NotaryException | NOTARISING, BROADCASTING |
| NotaryFlow | none | NotaryException (NotaryError types: TimeWindowInvalid, TransactionInvalid, WrongNotary), IllegalStateException, some via `check` assertions | REQUESTING, VALIDATING | | NotaryFlow | none | NotaryException (NotaryError types: TimeWindowInvalid, TransactionInvalid, WrongNotary), IllegalStateException, some via `check` assertions | REQUESTING, VALIDATING |
| NotaryChangeFlow | none | StateReplacementException | SIGNING, NOTARY | | NotaryChangeFlow | none | StateReplacementException | SIGNING, NOTARY |
| SendTransactionFlow | none | FetchDataFlow.HashNotFound (FlowException) | | | SendTransactionFlow | none | FetchDataFlow.HashNotFound (FlowException) | none |
| ReceiveTransactionFlow | none | SignatureException, AttachmentResolutionException, TransactionResolutionException, TransactionVerificationException | | | ReceiveTransactionFlow | none | SignatureException, AttachmentResolutionException, TransactionResolutionException, TransactionVerificationException | none |
| ResolveTransactionsFlow | none | FetchDataFlow.HashNotFound (FlowException), ExcessivelyLargeTransactionGraph (FlowException) | | | ResolveTransactionsFlow | none | FetchDataFlow.HashNotFound (FlowException), ExcessivelyLargeTransactionGraph (FlowException) | none |
| FetchAttachmentsFlow | none | FetchDataFlow.HashNotFound | | | FetchAttachmentsFlow | none | FetchDataFlow.HashNotFound | none |
| FetchTransactionsFlow | none | FetchDataFlow.HashNotFound | | | FetchTransactionsFlow | none | FetchDataFlow.HashNotFound | none |
| FetchDataFlow | some logging (info) | FetchDataFlow.HashNotFound | | | FetchDataFlow | some logging (info) | FetchDataFlow.HashNotFound | none |
| AbstractStateReplacementFlow.Instigator | none | StateReplacementException | SIGNING, NOTARY | | AbstractStateReplacementFlow.Instigator | none | StateReplacementException | SIGNING, NOTARY |
| AbstractStateReplacementFlow.Acceptor | none | StateReplacementException | VERIFYING, APPROVING | | AbstractStateReplacementFlow.Acceptor | none | StateReplacementException | VERIFYING, APPROVING |
| CollectSignaturesFlow | none | IllegalArgumentException via `require` assertions | COLLECTING, VERIFYING | | CollectSignaturesFlow | none | IllegalArgumentException via `require` assertions | COLLECTING, VERIFYING |
| CollectSignatureFlow | none | as above | | | CollectSignatureFlow | none | as above | none |
| SignTransactionFlow | none | FlowException, possibly other (general) Exception | RECEIVING, VERIFYING, SIGNING | | SignTransactionFlow | none | FlowException, possibly other (general) Exception | RECEIVING, VERIFYING, SIGNING |
| ContractUpgradeFlow | none | FlowException | | | ContractUpgradeFlow | none | FlowException | none |
| | | | |
Corda finance flows: Corda finance flows:

6
docs/source/design/sgx-infrastructure/details/attestation.md
View File

@ -1,9 +1,9 @@
### Terminology recap ### Terminology recap
**measurement**: The hash of an enclave image, uniquely pinning the code and related configuration * **measurement**: The hash of an enclave image, uniquely pinning the code and related configuration
**report**: A datastructure produced by an enclave including the measurement and other non-static properties of the * **report**: A datastructure produced by an enclave including the measurement and other non-static properties of the
running enclave instance (like the security version number of the hardware) running enclave instance (like the security version number of the hardware)
**quote**: A signed report of an enclave produced by Intel's quoting enclave. * **quote**: A signed report of an enclave produced by Intel's quoting enclave.
# Attestation # Attestation

26
docs/source/design/versioning/contract-versioning.md
View File

@ -39,7 +39,7 @@ Corda is designed such that the flow that builds the transaction (on its executi
But because input states are actually output states that are serialised with the previous transaction (built using a potentially different version of the contract), this means that states serialised with a version of the ContractJAR will need to be deserialisable with a different version. But because input states are actually output states that are serialised with the previous transaction (built using a potentially different version of the contract), this means that states serialised with a version of the ContractJAR will need to be deserialisable with a different version.
.. image:: resources/tx-chain.png .. image:: ../../resources/tx-chain.png
:scale: 25% :scale: 25%
:align: center :align: center
@ -77,7 +77,7 @@ This design is not about:
### Assumptions and trade-offs made for the current version ### Assumptions and trade-offs made for the current version
##### We assume that ContractStates will never change their semantics in a way that would impact other Contracts or Flows that depend on them. #### We assume that ContractStates will never change their semantics in a way that would impact other Contracts or Flows that depend on them.
E.g.: If various contracts depend on Cash, the assumption is that no new field will be added to Cash that would have an influence over the amount or the owner (the fundamental fields of Cash). E.g.: If various contracts depend on Cash, the assumption is that no new field will be added to Cash that would have an influence over the amount or the owner (the fundamental fields of Cash).
It is always safe to mix new CashStates with older states that depend on it. It is always safe to mix new CashStates with older states that depend on it.
@ -89,7 +89,7 @@ This is not a very strong definition, so we will have to create more formalised
If any contract breaks this assumption, in Corda 4 there will be no platform support the transition to the new version. The burden of coordinating with all the other cordapp developers and nodes is on the original developer. If any contract breaks this assumption, in Corda 4 there will be no platform support the transition to the new version. The burden of coordinating with all the other cordapp developers and nodes is on the original developer.
##### Flow to Flow communication could be lossy for objects that are not ContractStates or Commands. #### Flow to Flow communication could be lossy for objects that are not ContractStates or Commands.
Explanation: Explanation:
Flows communicate by passing around various objects, and eventually the entire TransactionBuilder. Flows communicate by passing around various objects, and eventually the entire TransactionBuilder.
@ -99,7 +99,7 @@ The decision was that the node that sends data would decide (if his version is h
The objects that live on the ledger like ContractStates and Commands that the other party actually has to sign, will not be allowed to lose any data. The objects that live on the ledger like ContractStates and Commands that the other party actually has to sign, will not be allowed to lose any data.
##### We assume that cordapp developers will correctly understand all implications and handle backwards compatibility themselves. #### We assume that cordapp developers will correctly understand all implications and handle backwards compatibility themselves.
Basically they will have to realise that any version of a flow can talk to any other version, and code accordingly. Basically they will have to realise that any version of a flow can talk to any other version, and code accordingly.
This get particularly tricky when there are reusable inline subflows involved. This get particularly tricky when there are reusable inline subflows involved.
@ -285,7 +285,7 @@ Terminology:
- Tx1, Tx2 - are transactions between parties. - Tx1, Tx2 - are transactions between parties.
#### Scenario 1 - Spending a state with an older contract. ### Scenario 1 - Spending a state with an older contract.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party) - V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0) - V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
@ -299,7 +299,7 @@ Terminology:
Solution: This was analysed above. It will be solved by the non-downgrade rule and the serialization engine changes. Solution: This was analysed above. It will be solved by the non-downgrade rule and the serialization engine changes.
#### Scenario 2: - Running an explicit upgrade written against an older contract version. ### Scenario 2: - Running an explicit upgrade written against an older contract version.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party) - V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0) - V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
- Another company creates a better com.gigacorp.token.GigaToken that is an UpgradedContract designed to replace the MegaToken via an explicit upgrade, but develop against V1 ( as V2 was not released at the time of development). - Another company creates a better com.gigacorp.token.GigaToken that is an UpgradedContract designed to replace the MegaToken via an explicit upgrade, but develop against V1 ( as V2 was not released at the time of development).
@ -313,7 +313,7 @@ Same as before:
Solution: This attack breaks the assumption we made that contracts will not be adding fields that change it fundamentally. Solution: This attack breaks the assumption we made that contracts will not be adding fields that change it fundamentally.
#### Scenario 3 - Flows installed by 2 peers compiled against different contract versions. ### Scenario 3 - Flows installed by 2 peers compiled against different contract versions.
- Alice runs V1 of the MegaToken FlowsJAR, while Bob runs V2. - Alice runs V1 of the MegaToken FlowsJAR, while Bob runs V2.
- Bob builds a new transaction where he transfers a state with accumulatedDebt To Alice. - Bob builds a new transaction where he transfers a state with accumulatedDebt To Alice.
- Alice is not able to correctly evaluate the business proposition, as she does not know that there even exists an accumulatedDebt field, but still signs it as if it was debt free. - Alice is not able to correctly evaluate the business proposition, as she does not know that there even exists an accumulatedDebt field, but still signs it as if it was debt free.
@ -321,7 +321,7 @@ Solution: This attack breaks the assumption we made that contracts will not be a
Solution: Solved by the assumption that peer-to-peer communication can be lossy, and the peer with the higher version is responsible to send the right data Solution: Solved by the assumption that peer-to-peer communication can be lossy, and the peer with the higher version is responsible to send the right data
#### Scenario 4 - Developer attempts to rename a field from one version to the next. ### Scenario 4 - Developer attempts to rename a field from one version to the next.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount ) - V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount )
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, currentDebt: Amount) - V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, currentDebt: Amount)
@ -331,7 +331,7 @@ This would break as soon as you try to spend a V1 state with V2, because there i
Solution: Not possible for now, as it breaks the serialisation evolution rules. Could be added as a new feature in the future. Solution: Not possible for now, as it breaks the serialisation evolution rules. Could be added as a new feature in the future.
#### Scenario 5 - Contract verification logic becomes more strict in a new version. General concerns. ### Scenario 5 - Contract verification logic becomes more strict in a new version. General concerns.
- V1: check that amount > 10 - V1: check that amount > 10
- V2: check that amount > 12 - V2: check that amount > 12
@ -349,7 +349,7 @@ The question is how important it is, that amount is >12?
Solution: This is not addressed in the current design doc. It needs to be explored in more depth. Solution: This is not addressed in the current design doc. It needs to be explored in more depth.
#### Scenario 6 - Contract verification logic becomes more strict in a new version. ??? ### Scenario 6 - Contract verification logic becomes more strict in a new version. ???
- V1: check that amount > 10 - V1: check that amount > 10
- V2: check that amount > 12 - V2: check that amount > 12
@ -362,7 +362,7 @@ Solution: This is not addressed in the current design doc. It needs to be explor
Solution: Same as Scenario 5. Solution: Same as Scenario 5.
#### Scenario 7 - Contract verification logic becomes less strict. ### Scenario 7 - Contract verification logic becomes less strict.
- V1: check that amount > 12 - V1: check that amount > 12
- V2: check that amount > 10 - V2: check that amount > 10
@ -373,7 +373,7 @@ Because there was no change in the actual structure of the state it means the fl
Solution: This should not require any change. Solution: This should not require any change.
#### Scenario 8 - Contract depends on another Contract. ### Scenario 8 - Contract depends on another Contract.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party) - V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0) - V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
@ -387,7 +387,7 @@ Alice swaps MegaToken-v2 for SuperToken-v1 with Bob in a transaction. If Alice s
Solution: Solved by the assumption we made that contracts don't change fundamentally. Solution: Solved by the assumption we made that contracts don't change fundamentally.
#### Scenario 9 - A new command is added or removed ### Scenario 9 - A new command is added or removed
- V1 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit - V1 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit
- V2 of com.megacorp.token.MegaToken has 4 Commands: Issue, Move, Exit, AddDebt - V2 of com.megacorp.token.MegaToken has 4 Commands: Issue, Move, Exit, AddDebt
- V3 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit - V3 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit