Skip to content
This repository has been archived by the owner on Mar 8, 2020. It is now read-only.

Commit

Permalink
readme updates to basic and car auction (#70)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Tobias-Hunter
Tobias-Hunter authored and Simon Stone committed Jul 12, 2017
1 parent dc92fb8 commit e18fd62
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 127 deletions.
58 changes: 49 additions & 9 deletions packages/basic-sample-network/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,57 @@
# Welcome to Hyperledger Composer!
# Basic Sample Business Network

This is the "Hello World" of Hyperledger Composer samples.
> This is the "Hello World" of Hyperledger Composer samples, which demonstrates the core functionality of Hyperledger Composer by changing the value of an asset.
This sample defines a business network composed of a single asset type (`SampleAsset`), a single participant type (`SampleParticipant`), a single transaction type (`SampleTransaction`), and a single event type (`SampleEvent`).
In the **Define** tab this in Basic Sample Business Network defines:

`SampleAssets` are owned by a `SampleParticipant`, and the value property on a `SampleAsset` can be modified by submitting a `SampleTransaction`. The `SampleTransaction` emits a `SampleEvent` that notifies applications of the old and new values for each modified `SampleAsset`.
**Asset**
`SampleAsset`

To get started inside Hyperledger Composer you can click the Test tab and create instances of `SampleAsset` and `SampleParticipant`. Make sure that the owner property on the `SampleAsset` refers to a `SampleParticipant` that you have created.
**Participant**
`SampleParticipant`

You can then submit a `SampleTransaction`, making sure that the asset property refers to an asset that you created earlier. After the transaction has been processed you should see that the value property on the asset has been modified, and that a `SampleEvent` has been emitted.
**Transaction**
`SampleTransaction`

The logic for updating the asset when a `SampleTransaction` is processed is written in `sample.js`.
**Event**
`SampleEvent`

Don't forget that you can import more advanced samples into Hyperledger Composer using the Import/Replace button.
SampleAssets are owned by a SampleParticipant, and the value property on a SampleAsset can be modified by submitting a SampleTransaction. The SampleTransaction emits a SampleEvent that notifies applications of the old and new values for each modified SampleAsset.

Have fun learning Hyperledger Composer!
To test this Business Network Definition in the **Test** tab:

Create a `SampleParticipant` participant:

```
{
"$class": "org.acme.sample.SampleParticipant",
"participantId": "Toby",
"firstName": "Tobias",
"lastName": "Hunter"
}
```

Create a `SampleAsset` asset:

```
{
"$class": "org.acme.sample.SampleAsset",
"assetId": "assetId:1",
"owner": "resource:org.acme.sample.SampleParticipant#Toby",
"value": "original value"
}
```

Submit a `SampleTransaction` transaction:

```
{
"$class": "org.acme.sample.SampleTransaction",
"asset": "resource:org.acme.sample.SampleAsset#assetId:1",
"newValue": "new value"
}
```

After submitting this transaction, you should now see the transaction in the Transaction Registry and that a `SampleEvent` has been emitted. As a result, the value of the `assetId:1` should now be `new value` in the Asset Registry.

Congratulations!
184 changes: 66 additions & 118 deletions packages/carauction-network/README.md
100644 → 100755
View file
Original file line number Diff line number Diff line change
@@ -1,188 +1,136 @@
# Hyperledger Composer Car Auction Demo
# Car Auction Business Network

This is an interactive, distributed, car auction demo, backed by Hyperledger Fabric. Invite participants to join your distributed auction, list assets for sale (setting a reserve price), and watch as assets that have met their reserve price are automatically transferred to the highest bidder at the end of the auction.
> This is an interactive, distributed, car auction demo. List assets for sale (setting a reserve price), and watch as assets that have met their reserve price are automatically transferred to the highest bidder at the end of the auction.
## Understanding the Business Network
In the **Define** tab for this network there is defined:

The easiest way to interact with the demo is using our work-in-progress [Hyperledger Composer web application](http://composer-playground.mybluemix.net). Hyperledger Composer allows you to define a business network (defining the data model and writing transaction processing logic), manage assets & participants and submit transactions.
**Assets:**
`Vehicle` `VehicleListing`

The data model for the auction business network is defined in a CTO model file, managed in GitHub [here](https://github.com/hyperledger/composer-sample-networks/blob/master/packages/carauction-network/models/auction.cto).
**Participants:**
`Member` `Auctioneer`

The data model is very simple (less than 50 lines). It defines the structure of the assets, participants and transactions for a very simple auction.

The business logic is defined in a single Javascript file [here](https://github.com/hyperledger/composer-sample-networks/blob/master/packages/carauction-network/lib/logic.js). The logic consists of two Javascript functions that are automatically invoked by the Hyperledger Composer runtime chain code when transactions are submitted for processing.
**Transactions:**
`Offer` `CloseBidding`

The `makeOffer` function is called when an `Offer` transaction is submitted. The logic simply checks that the listing for the offer is still for sale, and then adds the offer to the listing, and then updates the offer in the `VehicleListing` asset registry.

The `closeBidding` function is called when a `CloseBidding` transaction is submitted for processing. The logic checks that the listing is still for sale, sorts the offers by bid price, and then if the reserve has been met, transfers the ownership of the vehicle associated with the listing to the highest bidder. Money is transferred from the buyer's account to the seller's account, and then all the modified assets are updated in their respective registries.

Access control for the business network is defined [here](https://github.com/hyperledger/composer-sample-networks/blob/master/packages/carauction-network/permissions.acl).
To test this Business Network Definition in the **Test** tab:

### Developer Unit Testing
## Create an Auctioneer

> Note that if you `git clone` the [repository](https://github.com/hyperledger/composer-sample-networks) for the Business Network you can run a unit tests for the logic in the business network using the Hyperledger Composer embedded runtime which simulates a Hyperledger Fabric using a pure Javascript runtime. Simply run:
In the `Auctioneer` participant registry, create a new participant.

```
cd packages/carAuction-network
npm install
npm test
```
{
"$class": "org.acme.vehicle.auction.Auctioneer",
"email": "auction@acme.org",
"firstName": "Jenny",
"lastName": "Jones"
}
```

The unit test [here](https://github.com/hyperledger/composer-sample-networks/blob/master/packages/carauction-network/test/CarAuction.js) simulates an entire auction and checks that the business logic functions as expected.

## Connect to Composer

You can connect to Hyperledger Composer [here](http://composer-playground.mybluemix.net). If you have used Hyperledger Composer before you may need to clear your cached browser data.

> Hyperledger Composer currently only supports the web profile.
After you are connected make sure that Hyperledger Composer is communicating with the **'hyperledger'** connection profile by clicking the network dropdown at the top-right of the menu. The web profile allows you to test in isolation using a simulated Hyperledger, storing the ledger in browser local storage. The 'bluemix' connection profile is to a version of Hyperledger Composer deployed to bluemix.

## Setting Up the Demo

Before you can hold an auction you need to create and invite some participants to your business network and have something to sell!

### Create Your Participant & Issue an Identity Card

Switch to the Test tab, then click on the `User` participant registry, then click on the `Create Participant` button to create a new instance of a user.
## Create two Members

The JSON representation of the User should be:
In the `Member` participant registry, create two participants.

```
{
"$class": "org.acme.vehicle.auction.User",
"email": "a.participant@example.com",
"firstName": "Daniel",
"lastName": "Selman",
"balance": 10000
"$class": "org.acme.vehicle.auction.Member",
"balance": 5000,
"email": "memberA@acme.org",
"firstName": "Amy",
"lastName": "Williams"
}
```

Substitute `a.participant@example.com` with your email address. Congratulations you are now a participant in this business network!

> Hyperledger Composer does not yet support issuing and managing Hyperledger Fabric identities.
You now need to issue an identity card for this participant. Click the green ID card icon to the right of your participant. Enter an user id, for example `a.participant` and select the "Identity can be used to issue other identities?" checkbox so that this user has permission to invite other users into the business network.

You can switch between identities using the menu option at the top right of the screen.

### Create Assets

Now that you are a participant in the business network and have been issued an identity card you can own assets and take part in an auction.

#### Create a Vehicle

First, let's create a vehicle for auction.
```
{
"$class": "org.acme.vehicle.auction.Member",
"balance": 5000,
"email": "memberB@acme.org",
"firstName": "Billy",
"lastName": "Thompson"
}
```

Click on the `Vehicle` asset registry, and then click on the `Create Asset` button to create a new instance of a vehicle that can be auctioned.
## Create a Vehicle

The JSON representation of the Vehicle should be:
In the `Vehicle` asset registry, create a new asset of a vehicle owned by `memberA@acme.org`.

```
{
"$class": "org.acme.vehicle.auction.Vehicle",
"vin": "CAR_001",
"owner": "a.owner@example.com"
"vin": "vin:1234",
"owner": "resource:org.acme.vehicle.auction.Member#memberA@acme.org"
}
```

Substitute `a.owner@example.com` for the id of the participant you created above. Congratulations you are now the owner of the vehicle `CAR_001`!

#### Create a Vehicle Listing

The `VehicleListing` asset is used to list vehicles that are available for auction.
## Create a Vehicle Listing

Click on the click on the `VehicleListing` asset registry, and then click on the `Create Asset` icon to create a new instance of a vehicle listing.

The JSON representation of the `VehicleListing` should be:
In the `VehicleListing` asset registry, create a vehicle listing for car `vin:1234`.

```
{
"$class": "org.acme.vehicle.auction.VehicleListing",
"listingId": "LISTING_001",
"reservePrice": 4000,
"description": "Ford Mustang",
"listingId": "listingId:ABCD",
"reservePrice": 3500,
"description": "Arium Nova",
"state": "FOR_SALE",
"vehicle": "CAR_001"
"vehicle": "resource:org.acme.vehicle.auction.Vehicle#vin:1234"
}
```

Congratulations, you've just listed your Ford Mustang for auction, with a reserve price of $4000!

### Create Additional Participants

> Hyperledger Composer does not yet support inviting participants via a URL
An auction with one person is not much fun, so you need to either invite people to use Hyperledger Composer to create their own participants and identities, or you can do it for them. To make it easy for participants that you've created to join the business network (auction) when an identity is issued a personalised URL is generated that you can send to allow participants to join the business network in a single click.

You can send this text via email or Slack to give people an easy mechanism to launch Hyperledger Composer and join your business network.
You've just listed an Arium Nova for auction, with a reserve price of 3500!

## Bidding on a VehicleListing

As soon as a `VehicleListing` has been created (and is in the `FOR_SALE` state) participants can submit `Offer` transactions to bid on a vehicle listing.

Click on the Submit Transaction button to submit a new transaction for processing by the business network.
## Submit two Offer Transactions

The JSON payload should be:
Submit an `Offer` transaction, by submitting a transaction and selecting `Offer` from the dropdown.

```
{
"$class": "org.acme.vehicle.auction.Offer",
"bidPrice": 250.00,
"listing": "LISTING_001",
"user": "a.bidder@example.com"
"bidPrice": 2000,
"listing": "resource:org.acme.vehicle.auction.VehicleListing#listingId:ABCD",
"member": "resource:org.acme.vehicle.auction.Member#memberA@acme.org"
}
```

Substitute the id of the participant submitting the transaction for `a.bidder@example.com` and set the bid price as high as you'd like to bid. Remember the vehicle will only be sold if the reserve price is met and it will go to the highest bidder!

The `Offer` transaction is processed by the `makeOffer` function described above.
```
{
"$class": "org.acme.vehicle.auction.Offer",
"bidPrice": 3500,
"listing": "resource:org.acme.vehicle.auction.VehicleListing#listingId:ABCD",
"member": "resource:org.acme.vehicle.auction.Member#memberB@acme.org"
}
```

## End the Auction

To end the auction someone has to submit a `CloseBidding` transaction for the listing.

Click on the Submit Transaction button to submit a new transaction for processing by the business network.

The JSON payload should be:
To end the auction submit a `CloseBidding` transaction for the listing, by selecting `CloseBidding` from the dropdown.

```
{
"$class": "org.acme.vehicle.auction.CloseBidding",
"listing": "LISTING_001"
"listing": "resource:org.acme.vehicle.auction.VehicleListing#listingId:ABCD"
}
```

This simply indicates that the auction for `LISTING_001` is now closed, triggering the `closeBidding` function that was described above.
This simply indicates that the auction for `listingId:ABCD` is now closed, triggering the `closeBidding` function that was described above.


## Check the Results of the Auction

To see if the Vehicle was sold you need to click on the `Vehicle` asset registry and then check the owner of CAR_001. If the reserve price was met you should see that the owner of the vehicle has been modified.
To see the Vehicle was sold you need to click on the `Vehicle` asset registry to check the owner of the car. The reserve price was met by owner `memberB@acme.org` so you should see the owner of the vehicle is now `memberB@acme.org`.

If you check the state of the VehicleListing is should either be `SOLD` or `RESERVE_NOT_MET`.
If you check the state of the VehicleListing with `listingId:ABCD` is should be `SOLD`.

If you click on the 'User' asset registry you can check the balance of each User. You should see that the balance of the buyer has been debited by the amount they bid, whilst the balance of the seller has been credited.
If you click on the `Member` asset registry you can check the balance of each User. You should see that the balance of the buyer `memberB@acme.org` has been debited by `3500`, whilst the balance of the seller `memberA@acme.org` has been credited with `3500`.

## View the Blockchain

> Not yet supported in Hyperledger Composer
You can inspect the blocks and transaction created by Hyperledger during the course of the auction using the Hyperledger Explorer. Details TBD.

## Reset the Auction

To reset the auction you need to edit the VehicleListing to reset its state to `FOR_SALE`. Simply click on the `VehicleListing` registry and then click the pencil icon to update the VehicleListing back to its original state.

The JSON representation of the `VehicleListing` should be:

```
{
"$class": "org.acme.vehicle.auction.VehicleListing",
"listingId": "LISTING_001",
"reservePrice": 4000,
"description": "Ford Mustang",
"state": "FOR_SALE",
"vehicle": "CAR_001"
}
```
Congratulations!

0 comments on commit e18fd62

Please sign in to comment.