Fabric composer tips and tricks - working with current identity

If you work with Fabric Composer, the ACL (Access Control List) language is meant to handle access rules in the system. However there might be the case that you need to define access rules directly in the smart contract code in a hard coded way. If that is the case, you can ask the current identity with the getCurrentIdentity() API call and implement the corresponding access logic based on the identity information:

 var identity = getCurrentIdentity();    

 console.log(identity);

 console.log("identity namespace : " + identity);

 console.log("identity certificate : " + identity.certificate);

 console.log("identity identityId : " + identity.identityId);

 console.log("identity name : " + identity.name);

 console.log("identity participant identifier : " + identity.participant.$identifier);

 console.log("identity participant namespace : " + identity.participant.$namespace);

 console.log("identity participant type : " + identity.participant.$type);

Fabric composer tips and tricks - Cyclic ACL Rule detected, rule condition is invoking the same rule

If one of your asset or participant is not updated and you get the following error message like in the javascript console if you the use fabric composer online playground:"Fabric composer tips and tricks - Cyclic ACL Rule detected, rule condition is invoking the same rule" . The problem can be that you do not use the statement await before an update and two updates might happen parallel.  

Fabric composer tips and tricks - deleting asset from array

If you want to delete an element from an asset or participant that as a reference array to another asset or participant, the process is pretty similar to deleting an element from a javascript array:

1. Getting a registry for the asset or participant
const assetReg = await getAssetRegistry(namespace + '.Asset'); 

2. Getting an index of the asset or participant to be deleted
var index = asset.arrayOfReferences.indexOf(assetToBeDeleted);

3. Delete the index in a javascript style
  if (index > -1) {
     asset.arrayOfReferences.splice(index, 1);
  }

4. Update the asset
assetReg.update(asset);

Fabric composer tips and tricks - not updating without error message

Working with fabric composer, you can sometimes get the phenomena that some item is not being updated, however there is no error message or anything, the transaction is executed without any problems, only something is not updated. This can be caused by exchanging the getAssetRegistry with the getParticipantRegistry statement. If you experience such a phenomena, check if you try to update assets with the getAssetRegistry and update participants with the getParticipantRegistry statements.   

Fabric composer tips and tricks - importing external javascript library

In Hyperledger Fabric Composer at smart contact development importing external javascript libraries are not really supported at the moment. What you can basically do:

1. use the extra functionality on the client and server side and not directly in the smart contract. Pay attention that the smart contract is executed and evaluated on each endorsement peers of the Hyperledger Fabric architecture. This security guarantee is not always possible for most of the logic. Sometimes you can reconstruct your business logic in a way that the functionality provided by the external javascript library is executed on the client side and only the result is presented on the smart-contract side. 

2. if the code of the external javascript functionality is not huge, you can try to integrate the javascript files as extra files in your business network archive file. The framework references automatically the added javascript files. Certainly, you added files can not have external references. 

Fabric composer tips and tricks - return value of a transaction

Unfortunately there isn't possible to return value from a transaction in Hyperledger Fabric Composer. What you can do however:

- Emitting an event, like

  let retValEvent = getFactory().newEvent(namespace, 'RetValEvent');
  retValEvent.RetValue = "value";
    emit(retValEvent);

- writing the return value into the variables of an asset or participants. For fine-tuning the access rules, it might be possible to define a separate asset containing only the return values of the different transactions:

  asset ReturnValueAsser identified by retId {

    o String retId

    o String retValTransaction1

    o String retValTransaction2

    --> RelatedAsset relatedAsset

 }

Fabric composer tips and tricks - item with ID already exist but not visible

Sometimes if you work with the Fabric Composer online playground and you create an item from a transaction you get the error message that the given id already exist even if it is not directly visible in the asset list. This is actually a "feature" of the online playground, it happens if the old item with the old id already existed but it was deleted. For some reasons it is sometimes cached somewhere that can not be explicitly deleted. What you can do in such situations that you redeploy the business network archive file:

- Make sure that the latest version of the .bna (business network archive) is downloaded.

- Delete the existing business network in the online playground.

- Rdeploy the business network from the downloaded .bna file.

Fabric composer tips and tricks - getting type of an asset

If you use inheritance of assets in fabric composer and want to implement a transaction that execution is dependent on the actual asset type, you can use the following convention. Supposing that you have inheriting assets, like:

asset Ancestor identified by assetId {

  o String assetId

}

asset Descendant extends Ancestor{

}

you can query the exact type and the namespace of the asset with the following code:

toState.$type

toState.$namespace

Fabric composer tips and tricks - auto increment id of an asset

Classical problem is at Hyperledger Fabric composer that one want to auto increment the id of a newly created asset or participant. On way of reaching it that we query at the creation process all the number of the already existing assets and we simple increase the id by one. The following code demonstrates an example code:

    const assetReg = await getAssetRegistry(namespace + '.Asset');   

    let existingAssets = await assetReg.getAll();

  

    let numberOfAssets = 0;

    await existingAssets .forEach(function (asset) {

      numberOfAssets ++;

    });

    let newAssetId =  numberOfAssets +1;

Certainly, the construct does not protect from "double spending": if two assets will be created in the same round, both might get the same id, so one will be discarded as invalid. One way can be to overcome the difficulties is to use beside the incremented asset id another input parameter of the asset, like the asset name. 

Fabric composer tips and tricks - ACL for admin

If you start to modify or define the access control rules for a business blockchain network, pay attention that you coincidentally should not revoke code changing or code reading access for the networkAdmin role. If you do, it might happen, that you do not have access to your source code anymore. As a consequence, it is practical to start with general rules, that gives access to your admin role for everything, like:

rule NetworkAdminUser {

 description: "Grant business network administrators full access to user resources"

 participant: "org.hyperledger.composer.system.NetworkAdmin"

 operation: ALL

 resource: "**"

 action: ALLOW

}

rule NetworkAdminSystem {

 description: "Grant business network administrators full access to system resources"

  participant: "org.hyperledger.composer.system.NetworkAdmin"

  operation: ALL

  resource: "org.hyperledger.composer.system.**"

  action: ALLOW

} 

It is important to note that your participant is not your networkAdmin, so creating rules for the Participants but deleting for the networkAdmin will have the same effect.

Fabric composer tips and tricks - revoking CRUD right for a resource

If you revoke the Create, Update or Delete access for a role in Hyperledger Fabric Composer, you have to pay attention to the following things:

- The evaluation of the ACL file is executed rule by rule, the first rule that matches the to the participant, asset and operation will be applied. 

- If no rule matches but there is an ACL file, the access will be denied. 

- So one way to do it is to give a general access to the given participant which is evaluated if no deny rule is found. If you use the Hyperledger Fabric Composer online playground, you might as well give for the user during the testing access even for the system resources as well, because otherwise you can not test your code with that identity from the playground.

- As a first rule however you have to explicitly deny the operations on the specific resource. 

Rule first: 

rule UserHasNoCreateUpdateDeleteRirght {

    description: "User can not create update or delete "

    participant: "org.model.User"

    operation: CREATE, UPDATE, DELETE

    resource: "org.bicyclesharing.model.Asset"

    action: DENY

}

Rule second: 

rule UserHasAccessForAll {

    description: "User role has access for everything"

    participant: "org.model.User"

    operation: ALL

    resource: "**"

    action: ALLOW

}

Fabric composer tips and tricks - issue identity programmatically

If you want to issue a new identity for a participant, you can do it only from outside of your chaincode. Unfortunately there is no support for issuing identities inside your transaction or contract, which might make sense, hence this kind of a management is usually not part of the transnational logic. If you want to issue an identity from the outside world, what you have to do is the following:

1. Get your business network connection:

const BusinessNetworkConnection = require('composer-client').BusinessNetworkConnection;

2. Connect to your network, with a certain network card:

await businessNetworkConnection.connect('admin@mynetwork');

3. Issue new identity:

let result = await businessNetworkConnection.issueIdentity('Participans#email', 'name);

4. Close the connection:

await businessNetworkConnection.disconnect();  

Fabric composer tips and tricks - create an event

Creating and rising an event is not complicated at all in Fabric composer. You need the following steps:

1. Define your event in the mode file

event MyEvent {
  o <type> Property1
  o <type> Property2
}

2. Create your event in the your transaction javascript logic.

 let myEvent  = await getFactory().newEvent(namespace, 'MyEvent'); 

3. Filling the event properties:

  MyEvent.Property1 = <value1>;
  MyEvent.Property2 = <value2>;

4. Raising the event:

  emit(MyEvent);

Fabric composer tips and tricks - update assets or participants

To update an asset in Fabric composer in the transaction, you have to do the following steps:

0. Supposing you have a model file and an asset:

  asset AssetName identified by <primkey> {
    o <type>  <primkey>
    o <type>  RequiredField1 
    o <type>  RequiredField2 

   ...

  }

1. get a reference  to you asset. the reference usually comes from the input parameter, or following the object-graph of your input parameter. Optionally, you can query the asset registry for a certain asset or a set of assets. Having the reference, update the required fields.

  assetReference.RequiredField1 = newValue1;
  assetReference.RequiredField2 = newValue2;

    ...

2. get a factory object: it helps you to create other resources, events, assets and so on.

  const factory = getFactory();


3.  Get an asset registry to update your asset:

  const assetRegistry = await getAssetRegistry(namespace + 
    '.AssetName');

4.  add the new asset to the asset registry.

   await assetRegistry .update(assetReference);

optionally, you can update several references parallel.

   await assetRegistry.updateAll(assetReferences);

The participant case is similar, the only difference is that instead of the asset registry you should use the participant regisrtry.

Fabric composer tips and tricks - delete all data

If you want to delete all the data of a certain asset or participant category like in the case of a cleanup transaction, you have to do the following:

1. getting the asset or participant registry:

  const myAssetRegistry = await getAssetRegistry(namespace + 
    '.MyAsset'); 

2. querying the all elements of the given asset or participant registry:

  var allAssets = await myAssetRegistry.getAll();

3. delete all of the queried data:

  await myAssetRegistry.removeAll(allAssets);

Fabric composer tips and tricks - create a new concept

To create a concept in Fabric composer in the transaction is pretty similar to creating an asset, we consider the use case as you have to add a new concept as creating a new asset. you have to do the following steps:

0. Supposing you have a model file and an asset with a concept:

  concept ConceptName {
    o <type> Field1
    o <type> Field2
    ...
  }

  asset AsstetName identified by <primkey> {
    o <type> <primkey>
    o ConceptName ConceptField 
    ...
  }

1. get a factory object: it helps you to create other resources, events, assets, participants and so on.

  const factory = getFactory();

2. create a new concept with the help factory.newConcept after that  create a new asset with the help of the factory newResource call and with a new value for the primary key. After that update all the required fields both for your concept and for your asset and then associate the concept with the adequate field of your asset. 

  const newConcept = await factory.newConcept(namespace,
     'ConceptName');
  newConcept.Field1 = <value1>;
  newConcept.Field2 = <value2>;

  const newAsset = factory.newResource(namespace, 'AssetName',
     <primkey>);
  newAsset.ConceptField = newConcept ;
  newParticipant.RequiredField2 = value2;

    ...

3.  Get an asset registry to update your asset:

  const newAssetRegistry = await getAssetRegistry( 
      namespace + '.AssetName');

4.  add the new asset to the asset registry.

   await newAssetRegistry.add(newAsset);

Fabric composer tips and tricks - logging in a transaction

Error handling in Hyperledger Fabric composer it a little bit tricky, especially if it is on runtime errors and you want to create complex business logic with complex transactions. What you can do however is to simply use the standard javascript console for logging events and errors:

  console.log('My event');  

  console.log('My error');  

At executing the transaction like in the Fabric composer playground, the error message will be logged in the console of your browser. 

Fabric composer tips and tricks - create a new participant

To create a new participant in Fabric composer in the transaction is pretty similar to creating an asset, you have to do the following steps:

0. Supposing you have a model file and a participant:

  asset participantName identified by <primkey> {
    o <type>  <primkey>
    o <type>  RequiredField1 
    o <type>  RequiredField2 

   ...

  }

1. get a factory object: it helps you to create other resources, events, assets, participants and so on.

  const factory = getFactory();

2. create a new participant with the help of the factory newResource call and with a new value for the primary key. After that update all the required fields for your asset.

  const newParticipant = factory.newResource(namespace, 'ParticipantName', <primkey>);
  newParticipant.RequiredField1 = value1;
  newParticipant.RequiredField2 = value2;

    ...

3.  Get an participant registry to update your participant:

  const newParticipantRegistry = await getParticipantRegistry( 
      namespace + '.ParticipantName');

4.  add the new participant to the participant registry.

   await newParticipantRegistry.add(newParticipant);

Fabric composer tips and tricks - create a new asset

To create a new asset in Fabric composer in the transaction, you have to do the following steps:

0. Supposing you have a model file and an asset:

  asset AssetName identified by <primkey> {
    o <type>  <primkey>
    o <type>  RequiredField1 
    o <type>  RequiredField2 

   ...

  }

1. get a factory object: it helps you to create other resources, events, assets and so on.

  const factory = getFactory();

2. create a new asset with the help of the factory newResource call and with a new value for the primary key. After that update all the required fields for your asset.

  const newAsset=factory.newResource(namespace,'AssetName', <primkey>);
  newAsset.RequiredField1 = value1;
  newAsset.RequiredField2 = value2;

    ...

3.  Get an asset registry to update your asset:

  const newAssetRegistry = await getAssetRegistry(namespace + '.AssetName');

4.  add the new asset to the asset registry.

   await newAssetRegistry.add(newAsset);

Generating Solidity from Hyperledger Fabric Composer: asset inheritance

Inheritance can be translated from Hyperledger Composer to Solidity almost one to one. Both frameworks define inheritance among assets or smart contracts and there is the possibility to create abstract assets or smart contracts. The only difference is that Solidity supports multiply inheritance but Fabric Composer not really.