Skip to content

Commit

Permalink
docs(weaver): fix broken links in, and referring to, Weaver RFCs
Browse files Browse the repository at this point in the history
Signed-off-by: VRamakrishna <vramakr2@in.ibm.com>
  • Loading branch information
VRamakrishna authored and petermetz committed Jun 28, 2023
1 parent 2cff969 commit 7097ec0
Show file tree
Hide file tree
Showing 23 changed files with 62 additions and 46 deletions.
2 changes: 1 addition & 1 deletion weaver/core/relay/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ To run relay dummy client test:

`cargo run --bin client <port-number-of-requesting-relay> <address>`

NOTE: Please read through the addressing specification in the [rfcs](../../rfcs/formats/addressing.md). Make sure the network-type has a running supported driver and is specified in the config.
NOTE: Please read through the addressing specification in the [rfcs](../../rfcs/formats/views/addressing.md). Make sure the network-type has a running supported driver and is specified in the config.

EXAMPLE:

Expand Down
4 changes: 2 additions & 2 deletions weaver/rfcs/formats/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
-->
# Data Structures and Formats

This folder contains specifications of various data structures and formats used in Weaver components and [protocols](../protocols)
This folder contains specifications of various data structures and formats used in Weaver components and [protocols](../protocols).

Views and view addressing formats are described in the [views](./views) folder.

Expand All @@ -15,4 +15,4 @@ Message structures used by communication modules like relays and drivers are des

Policy schemas are described in the [policies](./policies) folder.

Network and network unit schemas are described in the [identities](./identities) folder.
Schemas for networks, network units, and identity management, are described in the [network](./network) folder.
6 changes: 3 additions & 3 deletions weaver/rfcs/formats/assets/exchange.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

## Locking Mechanisms for the Exchange Protocol

This document specifies the data formats used in the [cross-network asset exchange protocol](../../protocols/asset-exchange/). We envision supporting several distinct kinds of asset locking mechanisms for asset exchanges in Weaver, which are listed in and can be selected from an enumeration as follows:
This document specifies the data formats used in the [cross-network asset exchange protocol](../../protocols/asset-exchange/generic-htlc.md). We envision supporting several distinct kinds of asset locking mechanisms for asset exchanges in Weaver, which are listed in and can be selected from an enumeration as follows:
```protobuf
enum LockMechanism {
HTLC = 0;
Expand All @@ -22,7 +22,7 @@ Currently, only the [HTLC protocol](../../protocols/asset-exchange/generic-htlc.

## Representing Locks on Assets

To communicate locking instructions between the application layer or a contract and the [interoperation module](models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to lock assets (both fungible and non-fungible) is as follows:
To communicate locking instructions between the application layer or a contract and the [interoperation module](../../models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to lock assets (both fungible and non-fungible) is as follows:
```protobuf
message AssetLock {
LockMechanism lockMechanism = 1;
Expand Down Expand Up @@ -58,7 +58,7 @@ enum HashMechanism {

## Representing Claims on Assets

To communicate claiming instructions between the application layer or a contract and the [interoperation module](models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to claim assets (both fungible and non-fungible) is as follows:
To communicate claiming instructions between the application layer or a contract and the [interoperation module](../../models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to claim assets (both fungible and non-fungible) is as follows:
```protobuf
message AssetClaim {
LockMechanism lockMechanism = 1;
Expand Down
10 changes: 5 additions & 5 deletions weaver/rfcs/formats/assets/transfer.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
- Since: 21-Dec-2022

## Summary
This document specifies the data formats used in the [cross-network asset transfer protocol](../../protocols/asset-transfer/). The structures defined in this document are generic and the operations on them are generic (see the protocol specification for details.) These structures are oblivious to the specifications and semantics of any digital asset maintained by any DLT application (e.g., any application chaincode in Fabric or any CorDapp in Corda).
This document specifies the data formats used in the [cross-network asset transfer protocol](../../protocols/asset-transfer/generic.md). The structures defined in this document are generic and the operations on them are generic (see the protocol specification for details.) These structures are oblivious to the specifications and semantics of any digital asset maintained by any DLT application (e.g., any application chaincode in Fabric or any CorDapp in Corda).

## Representing an Asset Transfer Pledge

To communicate pledge (burning of an asset in a ledger for minting that asset in the same or in a differet ledger at a later point in time) details between the application layer or a contract and the [interoperation module](models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. Weaver supports atomic asset transfer between two parties, so a pledge agreement consists of the asset transfer commitment by a party in one ledger to an other party in a different ledger. The general structure to pledge assets (both fungible and non-fungible) is as follows (this structure can be extended in future when Weaver supports multi-party multi-asset transfers):
To communicate pledge (burning of an asset in a ledger for minting that asset in the same or in a differet ledger at a later point in time) details between the application layer or a contract and the [interoperation module](../../models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. Weaver supports atomic asset transfer between two parties, so a pledge agreement consists of the asset transfer commitment by a party in one ledger to an other party in a different ledger. The general structure to pledge assets (both fungible and non-fungible) is as follows (this structure can be extended in future when Weaver supports multi-party multi-asset transfers):
```protobuf
message AssetPledge {
bytes assetDetails = 1;
Expand All @@ -25,15 +25,15 @@ message AssetPledge {
uint64 expiryTimeSecs = 5;
}
```
- `assetDetails` field is a serialized asset details structure containing specific information about the asset being pledged. The details are opaque to the [interoperation module](models/infrastructure/interoperation-modules.md), which simply treats this asset as a digital blob that is ready to be pledged. Only the relevant application (e.g., chaincode, CorDapp) can parse and interpret the asset details, and must contain logic to perform additional checks and operations on the asset's state. Note that only the party owning the asset (captured as part of asset details structure) should be able to perform a pledge on the asset
- `assetDetails` field is a serialized asset details structure containing specific information about the asset being pledged. The details are opaque to the [interoperation module](../../models/infrastructure/interoperation-modules.md), which simply treats this asset as a digital blob that is ready to be pledged. Only the relevant application (e.g., chaincode, CorDapp) can parse and interpret the asset details, and must contain logic to perform additional checks and operations on the asset's state. Note that only the party owning the asset (captured as part of asset details structure) should be able to perform a pledge on the asset
- `localNetworkID` field is the identifier of the ledger in which the asset resides before the transfer (this is the network that exports the asset)
- `remoteNetworkID` field is the identifier of the ledger in which the asset resides after the transfer (this is the network that imports the asset)
- `recipient` field is the party in the importing network who owns the asset post the asset transfer
- `expiryTimeSecs` field is the pledge validity time period before which the `recipient` can mint the asset in the importing network `remoteNetworkID`

## Representing claims on pledged assets

To communicate claim (minting of the asset after transfer) details between the application layer or a contract and the [interoperation module](models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to claim assets (both fungible and non-fungible) is as follows:
To communicate claim (minting of the asset after transfer) details between the application layer or a contract and the [interoperation module](../../models/infrastructure/interoperation-modules.md) or across networks, we need common DLT-neutral structures. The general structure to claim assets (both fungible and non-fungible) is as follows:
```protobuf
message AssetClaimStatus {
bytes assetDetails = 1;
Expand All @@ -45,7 +45,7 @@ message AssetClaimStatus {
bool expirationStatus = 7;
}
```
- `assetDetails` field is a serialized asset details structure containing specific information about the asset being claimed. The details are opaque to the [interoperation module](models/infrastructure/interoperation-modules.md), which simply treats this asset as a digital blob that is ready to be claimed. Only the relevant application (e.g., chaincode, CorDapp) can parse and interpret the asset details, and must contain logic to perform additional checks and operations on the asset's state. Note that the party owning the asset (captured as part of asset details structure) is set to the party specified as the `recipient`
- `assetDetails` field is a serialized asset details structure containing specific information about the asset being claimed. The details are opaque to the [interoperation module](../../models/infrastructure/interoperation-modules.md), which simply treats this asset as a digital blob that is ready to be claimed. Only the relevant application (e.g., chaincode, CorDapp) can parse and interpret the asset details, and must contain logic to perform additional checks and operations on the asset's state. Note that the party owning the asset (captured as part of asset details structure) is set to the party specified as the `recipient`
- `localNetworkID` field is the identifier of the ledger in which the asset resides after the transfer (this is the network that imports the asset)
- `remoteNetworkID` field is the identifier of the ledger in which the asset resides before the transfer (this is the network that exports the asset)
- `recipient` field is the party in the importing network who owns the asset post the asset transfer; only this party can perform the claim on the asset that was pledged earlier
Expand Down
6 changes: 3 additions & 3 deletions weaver/rfcs/formats/communication/relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This document specifies the format of messages used in any protocol whenever the
## NetworkQuery

This message is created by client application to encapsulate the query for the relay.
Whenever a client application needs to query a foreign network for a [ledger state view](../../models/ledger/views.md), it must wrap the query comprising of a [view address](../views/addressing.md), a [verification policy](../policies/proof-verification.md), and other metadata, into a DLT-neutral structure as follows for the [relays](../../models/infrastructure/relay.md) that will accept and route the request.
Whenever a client application needs to query a foreign network for a [ledger state view](../../models/ledger/views.md), it must wrap the query comprising of a [view address](../views/addressing.md), a [verification policy](../policies/proof-verification.md), and other metadata, into a DLT-neutral structure as follows for the [relays](../../models/infrastructure/relays.md) that will accept and route the request.

```protobuf
message NetworkQuery {
Expand Down Expand Up @@ -103,7 +103,7 @@ service DataTransfer {
}
```

For more details on the `RequestState`, `SendState`, and `SendDriverState` API functions, see the [relay model](../../models/infrastructure/relays.md#api-for-other-relays)
For more details on the `RequestState`, `SendState`, and `SendDriverState` API functions, see the [relay model](../../models/infrastructure/relays.md#api-for-other-relays).

## Database

Expand All @@ -113,5 +113,5 @@ A relay should maintain a database to store remote queries and state of the loca

The local database should be used to store the state of the query i.e. [RequestState](../views/request-response.md#requeststate) payload with key as `request_id`. This `request_id` is a unique ID, which is generated for each query. The same `request_id` is used for all communications regarding this particular query request.

The remote database should be used to store the request [Query]((../views/request-response.md#query)) from remote (destination) relay (i.e. for which this relay is the source relay) to track the requests recieved from remote relay and then sent to the intended driver. In future, the remote database can be replaced with a task queue, where the requests coming from remote relay can be queued, before sending to the driver.
The remote database should be used to store the request [Query](../views/request-response.md#query) from remote (destination) relay (i.e. for which this relay is the source relay) to track the requests recieved from remote relay and then sent to the intended driver. In future, the remote database can be replaced with a task queue, where the requests coming from remote relay can be queued, before sending to the driver.

2 changes: 1 addition & 1 deletion weaver/rfcs/formats/network/corda-network-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ X500 name attribute types are:

There are various constraints placed on the X500 name, including maximum length
of attributes, valid country attribute, etc. For the full list of constraints,
see the [Corda docs for node identity](https://docs.corda.net/docs/corda-os/4.5/node-naming.html).
see the [Corda docs for node identity](https://docs.r3.com/en/platform/corda/4.7/enterprise/node/setup/node-naming.html).

## Authenticating Corda nodes as an external network

Expand Down
4 changes: 2 additions & 2 deletions weaver/rfcs/formats/network/iin_method.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

## Introduction

An Interoperation Identity Network (IIN) is a system built on a distributed shared ledger that supports registration of DIDs representing networks (e.g. permissioned consortium networks) and their units, as well as resolution of network DID documents from their DID. An IIN is also associated with one or more reputed [trust anchors](https://hyperledger-indy.readthedocs.io/projects/sdk/en/latest/docs/getting-started/indy-walkthrough.html#step-1-getting-trust-anchor-credentials-for-faber-acme-thrift-and-government), which play the important role of certifying (or validating) the identity of owners of those DIDs, as well as their memberships in their respective networks, in effect creating roots of trust for cross-network interoperations. Thus, IINs provide a foundation to enable the discovery and validation of blockchain/DLT networks and their participants. The IIN DID Method specification conforms to the requirements specified in [Decentralized Identifiers (DIDs) v1.0](https://w3c.github.io/did-core/). The IIN as a system is detailed further [here](./iin.md).
An Interoperation Identity Network (IIN) is a system built on a distributed shared ledger that supports registration of DIDs representing networks (e.g. permissioned consortium networks) and their units, as well as resolution of network DID documents from their DID. An IIN is also associated with one or more reputed [trust anchors](https://hyperledger-indy.readthedocs.io/projects/sdk/en/latest/docs/getting-started/indy-walkthrough.html#step-1-getting-trust-anchor-credentials-for-faber-acme-thrift-and-government), which play the important role of certifying (or validating) the identity of owners of those DIDs, as well as their memberships in their respective networks, in effect creating roots of trust for cross-network interoperations. Thus, IINs provide a foundation to enable the discovery and validation of blockchain/DLT networks and their participants. The IIN DID Method specification conforms to the requirements specified in [Decentralized Identifiers (DIDs) v1.0](https://w3c.github.io/did-core/). The IIN as a system is detailed further [here](../../models/identity/iin.md).

## IIN Method Syntax

Expand Down Expand Up @@ -87,7 +87,7 @@ Each participant in `networkParticipants` must already have a registered DID in

The DID, that is the `id` property in the Network DID document can be chosen by the network. The chosen `id` *MUST* end with ".network" and *MUST*.

See [Network DID Identity format](../../formats/identity.md) for details about Network DID format.
See [Network DID Identity format](./identity.md) for details about Network DID format.


##### Preparing Network DID creation request
Expand Down
10 changes: 5 additions & 5 deletions weaver/rfcs/formats/network/membership.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,18 @@

## Summary

- An external entity can represent a thing, person, organization or a group of entities such as a network.
- An external entity is known to the owners of a ledger by its identity.
- The set of identities representing the external entity is captured in a members list.
- Members are part of the overall [security domain](../models/security-domains.md#security-domains) defined on behalf of the external entity.
- An external entity can represent a thing, person, organization or a group of entities such as a network.
- An external entity is known to the owners of a ledger by its identity.
- The set of identities representing the external entity is captured in a members list.
- Members are part of the overall [security domain](../../models/security/security-domains.md) defined on behalf of the external entity.

## Members of a Security Domain

There are multiple strategies for capturing the members list of an external entity. If the external entity is a permissioned network, the members list can be represented by a set of certificate authorities (CAs), where each CA represents an organization in the network. This allows for any user or application in the external network to be identified as a valid member of the security domain as along as the certificate presented was issued by one of the CAs in the members list.

The members list can also be a set of public keys or a set of certificates with a valid chain of trust. This allows for individual members of the external entity to be directly identfied by their public key or certificate. An example of the former is for identifying the set of validators running a BFT consensus protocol in a permissionless network using Proof of Stake for sybil resistance.

Finally, the members map can be left empty ("\*"), indicating that any external entity is a valid member of the security domain. In these situations however, other approaches to authenticating the external entity (such as _traits_) can be used. See [security domains](../models/security-domains.md#security-domains) for discussions on this.
Finally, the members map can be left empty ("\*"), indicating that any external entity is a valid member of the security domain. In these situations however, other approaches to authenticating the external entity (such as _traits_) can be used. See [security domains](../../models/security/security-domains.md) for discussions on this.

A members object has the following structure:

Expand Down
4 changes: 2 additions & 2 deletions weaver/rfcs/formats/policies/access-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@

## Summary

- Access control policies are a means to control what objects on a ledger are accessbile to external entities and the type of actions these entities can exercise.
- Access control policies are applied against a [security domain](../../models/security/security-domains.md), which can represent entities such as a thing, an individual, an organization or a group of entities such as network.
- Access control policies are a means to control what objects on a ledger are accessbile to external entities and the type of actions these entities can exercise.
- Access control policies are applied against a [security domain](../../models/security/security-domains.md), which can represent entities such as a thing, an individual, an organization or a group of entities such as network.

## Defining Access Control Policies

Expand Down
Loading

0 comments on commit 7097ec0

Please sign in to comment.