Skip to main content
Governance is the foundation of TAPLE Core, defining the rules and policies that control how subjects behave within the network. This guide covers creating governance subjects and managing their lifecycle.

​
Understanding Governance

In TAPLE Core, governance is a special type of subject that defines:
  • Schemas: The structure and validation rules for subjects
  • Policies: Who can create, update, and validate events
  • Quorum: Required number of approvals for operations
  • Roles: Permissions assigned to network participants
The governance module is implemented in core/src/governance/governance.rs:1 and provides the GovernanceAPI interface for interacting with governance data.

​
Creating a Governance Subject

To create a governance subject, you need to send a Create event request with the special governance schema:
1
Generate Keys
2
First, generate cryptographic keys for the governance subject:
3
let governance_key = api
    .add_keys(KeyDerivator::Ed25519)
    .await
    .expect("Error generating keys");
4
Compose the Request
5
Create a StartRequest for the governance subject:
6
let create_subject_request = EventRequest::Create(StartRequest {
    governance_id: DigestIdentifier::default(),
    name: "".to_string(),
    namespace: "".to_string(),
    schema_id: "governance".to_string(),
    public_key: governance_key,
});
7
The governance_id is set to default (empty) because governance subjects are self-governing. The schema_id must be exactly "governance".
8
Sign the Request
9
Sign the request with your node’s key pair:
10
let signed_request = Signed::<EventRequest> {
    content: create_subject_request.clone(),
    signature: Signature::new(&create_subject_request, &node_key_pair).unwrap(),
};
11
Submit to the Node
12
Send the signed request to your TAPLE node:
13
let request_id = api.external_request(signed_request).await.unwrap();
14
Wait for Confirmation
15
Wait for the event notification to confirm creation:
16
let subject_id = if let Notification::NewEvent { sn: _, subject_id } = node
    .recv_notification()
    .await
    .expect("NewEvent notification received")
{
    subject_id
} else {
    panic!("Unexpected notification");
};

​
Retrieving Governance Data

​
Get Governance Subjects

Retrieve all governance subjects in the network: 
let governances = api
    .get_governances(
        "namespace".to_string(),
        None,  // from
        None,  // quantity
    )
    .await?;
The API method is defined in core/src/api/api.rs:207 and supports pagination through from and quantity parameters.

​
Get Schema Information

Retrieve the schema definition from governance: 
let schema = governance_api
    .get_schema(
        governance_id,
        schema_id,
        governance_version,
    )
    .await?;
This method is defined in core/src/governance/governance.rs:289 and returns the schema as a ValueWrapper.

​
Get Governance Version

Check the current version of a governance: 
let version = governance_api
    .get_governance_version(
        governance_id,
        subject_id,
    )
    .await?;
See core/src/governance/governance.rs:393 for the implementation.

​
Working with Governance Policies

​
Get Signers for a Stage

Retrieve the set of authorized signers for a validation stage: 
let signers = governance_api
    .get_signers(metadata, stage)
    .await?;
The ValidationStage enum defines different stages like Validate, Evaluate, and Approve.

​
Get Quorum Requirements

Determine the required quorum for a specific stage: 
let quorum = governance_api
    .get_quorum(metadata, stage)
    .await?;
Implemented in core/src/governance/governance.rs:331.

​
Check Invoke Permissions

Verify if an invoker has permission to perform an operation: 
let can_invoke = governance_api
    .get_invoke_info(metadata, stage, invoker)
    .await?;

​
Governance Updates

When governance is updated, the system broadcasts update messages: 
governance_api
    .governance_updated(
        governance_id,
        governance_version,
    )
    .await?;
This is implemented as a “tell” operation (fire-and-forget) in core/src/governance/governance.rs:426.
Governance updates can affect all subjects under that governance. Ensure proper testing before updating production governance.

​
Get Contracts

Retrieve the smart contracts associated with a governance: 
let contracts = governance_api
    .get_contracts(
        governance_id,
        governance_version,
    )
    .await?;
Returns a vector of (Contract, String) tuples containing contract definitions and their identifiers.

​
Check if Subject is Governance

Determine whether a subject ID represents a governance: 
let is_gov = governance_api
    .is_governance(subject_id)
    .await?;
Implemented in core/src/governance/governance.rs:413.

​
Best Practices

  1. Version Control: Always track governance versions to ensure compatibility
  2. Testing: Test governance changes in a development environment first
  3. Quorum Settings: Set appropriate quorum values to balance security and availability
  4. Schema Validation: Ensure schemas are well-defined before deployment
  5. Access Control: Carefully define roles and permissions in governance policies

​
Error Handling

Common governance errors include:
  • GovernanceNotFound: The specified governance doesn’t exist
  • InvalidGovernanceID: The governance identifier is malformed
  • SubjectNotFound: Referenced subject doesn’t exist
  • ChannelClosed: Communication channel with governance module failed
Always handle these errors appropriately in your application code.

Build docs developers (and LLMs) love

Get started for freeTalk to us