Membership Representation in Corda 4.6

A guide for Corda Developers on one of our favourite new features

Corda 4.6 now allows you to create business networks and integrate them into your applications. But what is a business network, and why should I care? Check out the docs on Corda business network management here.

A distributed application on Corda is not as powerful standalone. It needs a group of contextual peers (nodes representing organizations that share a common business objective). These nodes need to share the ability to discover each other’s fundamental network identity and IP address and agree on some standards to communicate with one another — which today means being in the same Corda network. Finally, they need an application in common that gives that communication some meaning.

We refer to groups of nodes that meet these criteria as a Business Network.

We refer to the node entity that manages groups of nodes as a Business Network Operator.

We’re aiming at solving three problems:

• Enable developers and operators to define additional identity attributes specific to their business context or required to be collected and managed for a given application.
• Enable business network operators to model relationships between nodes using roles or membership groups.
• Enable CorDapp developers to query for this membership information — to drive the relevant logic.

Developers can now represent users on CorDapps via membership attestations, membership lists, and network metadata, enabling them to query participants’ membership information to tailor the experience and end-user access to features. This distributed membership information enables business network operators to manage network participation more effectively, independently of the network operator.

What does that mean?

Here’s the idea; A Corda Node can belong to multiple membership lists. A Node within a business network can bootstrap a membership, query a membership list, or request a membership attestation change. A Membership attestation is an extensible identity attribute.

Membership attestation and membership lists are authoritative and current and cannot be tampered with. A membership list is a dynamic group of membership attestations as defined by the developer. A membership list is private and exists on a need to know basis.

You can create your lists, customize their access controls, and outline the lifecycle management events you want to support–pretty sweet.

And of course, we’ve added documentation around this for CorDapp developers to manage lifecycle events (issuance, suspension, revocation, metadata amendments), and feature-based entitlements from attestation, segment discovery within a business network, make use of identity attributes, etc.. As always, we’ll have some samples available that can make this clearer to implement.

An Example

For example, different applications may take on different roles or be permitted to perform various operations. Maybe only some participants of a shared Corda network are allowed to use specific applications or discover individual peers within the application context.

Required Valid membership

Let’s say you want to ensure that only active members can access certain features of your application — while you want the ability to suspend participants (e.g., for contractual reasons) or even revoke them if they are no longer to be considered a member.

By modeling this problem using membership, you can add this check-in to your CorDapp and administer your clients’ membership status using our provided administrative tooling. Suppose a contract expires or a customer leaves the network. In that case, you can change their membership attestation, and they won’t be able to use your application or be discovered by your other customers.

This might sound a little bit confusing when you imagine it from the network operator’s perspective, who you might expect can already see and access every node on the network. Remember that often, a party runs and maintains its own Corda node in a more extensive network. Based on feedback from users, there is often a need for a concept of membership.

While network identity and location are known in a shared network to CorDapps, the way participants experience peers’ discovery is typically through the application.

Membership attestation becomes much more useful from the perspective of one of these individual nodes that want to track unique or specific information about other Corda nodes.

Another Example

You can create a list of nodes for any reason, and as a developer, I can query against that list of nodes and control access to them.

Premium Access modeled in Corda

Let’s say I want to run my application, but ensure that only premium customers can access given information or even discover specific peer nodes. I can now model that using membership and just query for it in my CorDapp.

This blog post wouldn’t be complete without some code examples! So here are some examples as the code can be pretty easy to add to flows you’ve already built previously.

Creating a Business Network

val myIdentity: BNIdentity = createBusinessNetworkIdentity() // mock method that creates an instance of a class implementing [BNIdentity]
val businessNetworkId = UniqueIdentifier()
val groupId = UniqueIdentifier()
val notary = serviceHub.networkMapCache.notaryIdentities.first()

subFlow(CreateBusinessNetworkFlow(businessNetworkId, myIdentity, groupId, "Group 1", notary))

Activating Business Network Membership

val bnService = serviceHub.cordaService(BNService::class.java)
val networkId: UniqueIdentifier = ... // id of the business network for which membership activation is done
val newMemberPartyObject = ... // get the [Party] object of the member whose membership is being activated
val membershipId = bnService.getMembership(networkId, newMemberPartyObject)
val groupName = ... // name of the group which the member will be assigned to
val groupId = ... // identifier of the group which the member will be assigned to
val notary = serviceHub.networkMapCache.notaryIdentities.first())

subFlow(ActivateMembershipFlow(membershipId, notary)
// add newly activated member to a membership list
val newParticipantsList = bnService.getBusinessNetworkGroup(groupId).state.data.participants.map {
    bnService.getMembership(networkId, it)!!.state.data.linearId
} + membershipId

subFlow(ModifyGroupFlow(groupId, groupName, newParticipantsList, notary))

This release introduces new APIs to manage the lifecycle of a membership attestation. It showcases best practices to manage memberships, drive entitlements, and set granular privacy and permissions within your business network.

If you’d like to read more about Corda 4.6, you can check out our post released last summer. You can watch the milestone development directly at ground zero on GitHub. And of course, there’s always the Corda documentation on business networks.

In the future, we’re planning on creating management tooling for operators, health check monitoring, and notary exclusivity!

— Special Thanks to Gabriele Farei for helping me with writing this post.

Want to learn more about building awesome blockchain applications on Corda? Be sure to visit https://corda.net, check out our community page to learn how to connect with other Corda developers, and sign up for one of our newsletters for the latest updates.

— David Awad is a Developer Evangelist at R3, an enterprise blockchain software firm working with a global ecosystem of more than 350 participants across multiple industries from both the private and public sectors to develop on Corda, its open-source blockchain platform, and Corda Enterprise, a commercial version of Corda for enterprise usage.

Follow David on Twitter here.