Governance Zome (zome_gouvernance) Documentation
The Governance zome implements the core economic coordination and validation infrastructure for the nondominium ecosystem, providing ValueFlows-compliant economic event logging, commitment management, Private Participation Receipt (PPR) reputation system, and comprehensive agent validation workflows. It serves as the governance backbone enabling decentralized resource sharing with embedded accountability and cryptographically-secured reputation tracking.
Post-MVP (target architecture): unified transition evaluation is specified to optionally enforce Unyt economic closure (EconomicAgreement rules, rave_hash; documentation/requirements/ndo_prima_materia.md §6.6) and Flowsta identity checks (IdentityVerification, FlowstaIdentity; §6.7). See documentation/archives/governance.md §3.7, documentation/requirements/post-mvp/unyt-integration.md, and documentation/requirements/post-mvp/flowsta-integration.md. MVP coordinator paths (e.g. promotion validation) precede that consolidation.
Core Data Structures
VfAction Enum
#![allow(unused)] fn main() { pub enum VfAction { // Standard ValueFlows transfer actions Transfer, // Transfer ownership/custody Move, // Move a resource from one location to another // Standard ValueFlows production/consumption actions Use, // Use a resource without consuming it Consume, // Consume/destroy a resource Produce, // Create/produce a new resource Work, // Apply work/labor to a resource // Standard ValueFlows modification actions Modify, // Modify an existing resource Combine, // Combine multiple resources Separate, // Separate one resource into multiple // Standard ValueFlows quantity adjustment actions Raise, // Increase quantity/value of a resource Lower, // Decrease quantity/value of a resource // Standard ValueFlows citation/reference actions Cite, // Reference or cite a resource Accept, // Accept delivery or responsibility // nondominium-specific actions InitialTransfer, // First transfer by a Simple Agent AccessForUse, // Request access to use a resource TransferCustody, // Transfer custody (nondominium specific) } }
ValueFlows Compliance: Complete economic action vocabulary supporting all standard and nondominium-specific actions Type Safety: Replaces string-based actions with compile-time validation Helper Methods: Resource validation, quantity modification, custody change detection
VfAction Helper Methods
#![allow(unused)] fn main() { impl VfAction { pub fn requires_existing_resource(&self) -> bool; // Resource validation pub fn creates_resource(&self) -> bool; // New resource detection pub fn modifies_quantity(&self) -> bool; // Quantity change detection pub fn changes_custody(&self) -> bool; // Custody transfer detection } }
ValidationReceipt Entry
#![allow(unused)] fn main() { pub struct ValidationReceipt { pub validator: AgentPubKey, // Agent providing validation // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. // For collective/bot validators, the signing authority is the designated // operator key. The governance evaluation must resolve AgentContext → // effective AgentPubKey before capability token validation. pub validated_item: ActionHash, // Item being validated (Resource, Event, etc.) pub validation_type: String, // Type: "resource_approval", "agent_promotion", "role_validation" pub approved: bool, // Validation result pub notes: Option<String>, // Optional validation notes pub validated_at: Timestamp, // Validation timestamp } }
Governance: Core validation infrastructure for all governance workflows Audit Trail: Complete tracking of all community validations Flexibility: Supports multiple validation types with contextual notes
EconomicEvent Entry
#![allow(unused)] fn main() { pub struct EconomicEvent { pub action: VfAction, // Economic action performed pub provider: AgentPubKey, // Agent providing the resource/service // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. pub receiver: AgentPubKey, // Agent receiving the resource/service // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. pub resource_inventoried_as: ActionHash, // Link to the EconomicResource pub affects: ActionHash, // Link to the affected EconomicResource pub resource_quantity: f64, // Quantity involved in the event pub event_time: Timestamp, // When the event occurred pub note: Option<String>, // Optional event description } }
ValueFlows Compliance: Complete economic event specification Resource Tracking: Links to affected resources for audit trails Action Integration: Uses type-safe VfAction enum
Commitment Entry
#![allow(unused)] fn main() { pub struct Commitment { pub action: VfAction, // Economic action committed to pub provider: AgentPubKey, // Provider of the commitment // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. pub receiver: AgentPubKey, // Receiver of the commitment // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. pub resource_inventoried_as: Option<ActionHash>, // Specific resource if applicable pub resource_conforms_to: Option<ActionHash>, // Resource specification if general pub input_of: Option<ActionHash>, // Optional link to a Process pub due_date: Timestamp, // Commitment due date pub note: Option<String>, // Optional commitment description pub committed_at: Timestamp, // When commitment was made } }
Planning: Economic planning and commitment tracking Flexibility: Supports both specific and general resource commitments Due Date Management: Time-bound commitments with expiry
Claim Entry
#![allow(unused)] fn main() { pub struct Claim { pub fulfills: ActionHash, // References the Commitment pub fulfilled_by: ActionHash, // References the resulting EconomicEvent pub claimed_at: Timestamp, // When claim was made pub note: Option<String>, // Optional claim description } }
Fulfillment Tracking: Links commitments to their actual execution Accountability: Creates audit trail of promise vs. delivery Performance Data: Basis for reputation calculation
ResourceValidation Entry
#![allow(unused)] fn main() { pub struct ResourceValidation { pub resource: ActionHash, // Link to the EconomicResource being validated pub validation_scheme: String, // e.g., "2-of-3", "simple_majority" pub required_validators: u32, // Number of validators required pub current_validators: u32, // Number of validators who have validated pub status: String, // "pending", "approved", "rejected" pub created_at: Timestamp, // Validation creation time pub updated_at: Timestamp, // Last update time } }
Multi-Reviewer Validation: Support for complex validation schemes Progress Tracking: Monitor validation progress in real-time Configurable Schemes: Flexible validation requirements
Private Participation Receipt (PPR) System
ParticipationClaimType Enum
#![allow(unused)] fn main() { pub enum ParticipationClaimType { // Genesis Role - Network Entry ResourceCreation, // Creator receives this for successful resource contribution ResourceValidation, // Validator receives this for network validation performed // Core Usage Role - Custodianship CustodyTransfer, // Outgoing custodian receives this for responsible custody transfer CustodyAcceptance, // Incoming custodian receives this for custody acceptance // Intermediate Roles - Specialized Services MaintenanceCommitmentAccepted, // Maintenance agent receives this for accepted commitment MaintenanceFulfillmentCompleted, // Maintenance agent receives this for completed fulfillment StorageCommitmentAccepted, // Storage agent receives this for accepted commitment StorageFulfillmentCompleted, // Storage agent receives this for completed fulfillment TransportCommitmentAccepted, // Transport agent receives this for accepted commitment TransportFulfillmentCompleted, // Transport agent receives this for completed fulfillment GoodFaithTransfer, // Custodian receives this for good faith transfer to service provider // Network Governance DisputeResolutionParticipation, // For constructive participation in conflict resolution ValidationActivity, // For performing validation duties beyond specific transactions RuleCompliance, // For consistent adherence to governance protocols // Resource End-of-Life Management EndOfLifeDeclaration, // Declaring agent receives this for end-of-life declaration EndOfLifeValidation, // Expert validator receives this for end-of-life validation // TODO (G6, REQ-GOV-15 — post-MVP): add new claim types for governance ceremonies: // AffiliationRecordSigned, // Issued when agent signs AffiliationRecord (ToP ceremony) // GovernanceRoleGranted, // Issued when collective agent is granted a governance role // These extend PPR tracking to cover formal governance participation beyond economic events. } }
Comprehensive Coverage: 16 claim types covering all economic interactions Role-Based Categories: Claims organized by agent roles and interaction types Reputation Foundation: Each claim type contributes to reputation calculation
PerformanceMetrics Structure
#![allow(unused)] fn main() { pub struct PerformanceMetrics { pub timeliness: f64, // Punctuality score (0.0 to 1.0) pub quality: f64, // Task quality score (0.0 to 1.0) pub reliability: f64, // Commitment fulfillment reliability (0.0 to 1.0) pub communication: f64, // Communication effectiveness (0.0 to 1.0) pub overall_satisfaction: f64, // Counterparty satisfaction (0.0 to 1.0) pub notes: Option<String>, // Optional contextual notes } }
Quantitative Assessment: Numerical scores for objective reputation calculation Weighted Average: Customizable weights for different aspects of performance Validation: All scores must be within valid range (0.0 to 1.0)
CryptographicSignature Structure
#![allow(unused)] fn main() { pub struct CryptographicSignature { pub recipient_signature: Signature, // Signature from PPR owner pub counterparty_signature: Signature, // Signature from counterparty pub signed_data_hash: [u8; 32], // Hash of signed data for verification pub signed_at: Timestamp, // When signatures were created } }
Bilateral Authentication: Both parties sign to acknowledge the interaction Cryptographic Security: Tamper-evident signatures for reputation integrity Verification Support: Complete context for signature verification
PrivateParticipationClaim Entry
#![allow(unused)] fn main() { pub struct PrivateParticipationClaim { // Standard ValueFlows fields pub fulfills: ActionHash, // References the commitment fulfilled pub fulfilled_by: ActionHash, // References the economic event pub claimed_at: Timestamp, // PPR-specific extensions pub claim_type: ParticipationClaimType, pub performance_metrics: PerformanceMetrics, pub bilateral_signature: CryptographicSignature, // Additional context pub counterparty: AgentPubKey, // The other agent involved in the interaction // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP. // Bot agents generate PPRs with their operator's AgentPubKey as the // accountable counterparty. pub resource_hash: Option<ActionHash>, // Optional link to the resource involved pub notes: Option<String>, // Optional contextual notes } }
Privacy: Stored as private entry, accessible only to the claim owner Complete Context: Links commitment, event, performance, and cryptographic proof Reputation Data: Foundation for trust and reputation calculation
ReputationSummary Structure
#![allow(unused)] fn main() { pub struct ReputationSummary { pub total_claims: u32, // Total number of participation claims pub average_performance: f64, // Average performance score across all claims pub creation_claims: u32, // Resource creation and validation claims pub custody_claims: u32, // Custody-related claims pub service_claims: u32, // Service provision claims pub governance_claims: u32, // Governance participation claims pub end_of_life_claims: u32, // End-of-life management claims pub period_start: Timestamp, // Time period this summary covers pub period_end: Timestamp, // End of time period pub agent: AgentPubKey, // Agent this summary belongs to pub generated_at: Timestamp, // When summary was generated } }
Privacy-Preserving: Share reputation without revealing individual claims Category Breakdown: Reputation scores by interaction type Time-Period Based: Configurable time windows for reputation calculation
API Functions
Economic Event Management
log_economic_event(input: LogEconomicEventInput) -> ExternResult<LogEconomicEventOutput>
Logs an economic event to the distributed ledger.
Input:
#![allow(unused)] fn main() { pub struct LogEconomicEventInput { pub action: VfAction, pub provider: AgentPubKey, pub receiver: AgentPubKey, pub resource_inventoried_as: ActionHash, pub affects: ActionHash, pub resource_quantity: f64, pub note: Option<String>, } }
Business Logic:
- Validates action compatibility with resource state
- Creates economic event with timestamp
- Links to affected resource for audit trail
- Triggers PPR generation if applicable
Integration: Automatically generates appropriate PPR claims Validation: Cross-zome validation with resource and person zomes
log_initial_transfer(input: LogInitialTransferInput) -> ExternResult<LogEconomicEventOutput>
Special function for Simple Agent's first resource transfer.
Business Logic: Handles special case for agent progression Validation: Validates this is the agent's first transfer Integration: May trigger Simple Agent promotion workflow
get_all_economic_events() -> ExternResult<Vec<EconomicEvent>>
Retrieves all economic events (with appropriate access control).
Privacy: Filters events based on participant access rights Performance: Efficient query via economic event anchors
get_events_for_resource(resource_hash: ActionHash) -> ExternResult<Vec<EconomicEvent>>
Gets all economic events affecting a specific resource.
Pattern: Follows resource-to-events link chain Use Case: Complete resource lifecycle and history
get_events_for_agent(agent: AgentPubKey) -> ExternResult<Vec<EconomicEvent>>
Gets all economic events involving a specific agent.
Pattern: Queries agent participation in economic activities Use Case: Agent's economic activity history
Commitment Management
propose_commitment(input: ProposeCommitmentInput) -> ExternResult<ProposeCommitmentOutput>
Creates a new economic commitment.
Input:
#![allow(unused)] fn main() { pub struct ProposeCommitmentInput { pub action: VfAction, pub provider: AgentPubKey, pub receiver: AgentPubKey, pub resource_conforms_to: Option<ActionHash>, pub input_of: Option<ActionHash>, pub due_date: Timestamp, pub note: Option<String>, } }
Business Logic:
- Validates commitment feasibility
- Creates commitment with automatic expiration
- Links to resource specification if applicable
- Sets up claim fulfillment tracking
Integration: Creates framework for PPR generation upon fulfillment
get_all_commitments() -> ExternResult<Vec<Commitment>>
Retrieves all commitments (with appropriate access control).
Privacy: Filters commitments based on participant access rights
get_commitments_for_agent(agent: AgentPubKey) -> ExternResult<Vec<Commitment>>
Gets all commitments involving a specific agent.
Pattern: Queries agent as provider or receiver Use Case: Agent's commitment portfolio and obligations
claim_commitment(input: ClaimCommitmentInput) -> ExternResult<ClaimCommitmentOutput>
Claims fulfillment of a commitment, creating the link to an economic event.
Business Logic:
- Validates economic event fulfills commitment requirements
- Creates claim linking commitment to event
- Triggers PPR generation for both parties
- Updates reputation metrics
Integration: Core mechanism for PPR generation
get_all_claims() -> ExternResult<Vec<Claim>>
Retrieves all claims (with appropriate access control).
get_claims_for_commitment(commitment_hash: ActionHash) -> ExternResult<Vec<Claim>>
Gets all claims for a specific commitment.
Pattern: Track commitment fulfillment history Use Case: Commitment performance analysis
Validation System
create_validation_receipt(input: CreateValidationReceiptInput) -> ExternResult<Record>
Creates a validation receipt for any validated item.
Input:
#![allow(unused)] fn main() { pub struct CreateValidationReceiptInput { pub validated_item: ActionHash, pub validation_type: String, pub approved: bool, pub notes: Option<String>, } }
Business Logic:
- Records validator's assessment
- Links to validated item for audit trail
- Creates validation history
- May trigger PPR generation for validation activity
get_validation_history(item_hash: ActionHash) -> ExternResult<Vec<ValidationReceipt>>
Gets complete validation history for an item.
Pattern: Follows validated_item_to_receipt links Use Case: Comprehensive validation audit trail
get_all_validation_receipts() -> ExternResult<Vec<ValidationReceipt>>
Retrieves all validation receipts (with appropriate access control).
create_resource_validation(input: CreateResourceValidationInput) -> ExternResult<Record>
Creates a resource validation workflow.
Input:
#![allow(unused)] fn main() { pub struct CreateResourceValidationInput { pub resource: ActionHash, pub validation_scheme: String, // "2-of-3", "simple_majority", etc. pub required_validators: u32, } }
Business Logic:
- Creates validation workflow with specified scheme
- Tracks validation progress
- Manages validator assignments
- Determines final validation outcome
check_validation_status(validation_hash: ActionHash) -> ExternResult<String>
Checks the current status of a validation workflow.
Returns: "pending" | "approved" | "rejected" Use Case: Monitor validation progress
validate_new_resource(input: ValidateNewResourceInput) -> ExternResult<ValidationResult>
Validates a new resource according to community standards.
Cross-Zome Integration: Works with resource zome for validation Validation Logic: Applies governance rules and community standards Outcome: May approve resource or require further validation
Agent Validation and Promotion
validate_agent_identity(input: ValidateAgentIdentityInput) -> ExternResult<ValidationResult>
Validates agent identity and private information for promotion.
Input:
#![allow(unused)] fn main() { pub struct ValidateAgentIdentityInput { pub agent: AgentPubKey, pub resource_hash: ActionHash, pub private_data_hash: Option<ActionHash>, } }
Business Logic:
- Cross-zome call to person zome for private data access
- Validates agent meets promotion requirements
- Creates validation receipt for audit trail
- May trigger agent promotion workflow
Privacy: Respects private data access controls
validate_agent_for_promotion(input: ValidateAgentForPromotionInput) -> ExternResult<ValidationResult>
Comprehensive validation for agent promotion to higher capability levels.
Validation Logic:
- Checks resource creation requirements
- Validates community participation
- Evaluates PPR-based reputation
- Assesses governance understanding
validate_agent_for_custodianship(input: ValidateAgentForCustodianshipInput) -> ExternResult<ValidationResult>
Validates agent suitability for resource custodianship.
Validation Logic:
- Capability level validation
- PPR reputation assessment
- Custody history review
- Community standing evaluation
validate_specialized_role(input: ValidateSpecializedRoleInput) -> ExternResult<ValidationResult>
Validates agent for specialized roles (Transport, Repair, Storage).
Role-Specific Validation:
- Technical capability assessment
- Equipment/facility requirements
- Safety and compliance validation
- Performance history review
Private Participation Receipt (PPR) System
issue_participation_receipts(input: IssueParticipationReceiptsInput) -> ExternResult<IssueParticipationReceiptsOutput>
Issues PPRs to both parties involved in an economic interaction.
Input:
#![allow(unused)] fn main() { pub struct IssueParticipationReceiptsInput { pub fulfills: ActionHash, pub fulfilled_by: ActionHash, pub provider: AgentPubKey, pub receiver: AgentPubKey, pub claim_types: Vec<ParticipationClaimType>, pub provider_metrics: PerformanceMetrics, pub receiver_metrics: PerformanceMetrics, pub resource_hash: Option<ActionHash>, pub notes: Option<String>, } }
Business Logic:
- Creates private PPR entries for both parties
- Generates bilateral cryptographic signatures
- Links to commitment and economic event
- Stores performance metrics for reputation calculation
Privacy: Private entries accessible only to respective owners Security: Cryptographic signatures prevent tampering
sign_participation_claim(input: SignParticipationClaimInput) -> ExternResult<SignParticipationClaimOutput>
Signs a participation claim with bilateral authentication.
Cryptography: Creates cryptographic signatures for both parties Verification: Supports signature verification for authenticity Integration: Used in PPR creation and validation workflows
validate_participation_claim_signature(input: ValidateParticipationClaimSignatureInput) -> ExternResult<bool>
Validates the cryptographic signatures on a participation claim.
Security: Ensures claim authenticity and integrity Verification: Supports cross-agent claim verification
validate_participation_claim_signature_enhanced(input: ValidateParticipationClaimSignatureInput) -> ExternResult<EnhancedValidationResult>
Enhanced signature validation with detailed verification results.
Additional Features:
- Signature timestamp validation
- Agent verification status
- Claim context validation
- Detailed security assessment
get_my_participation_claims(filter: Option<PPRFilter>) -> ExternResult<Vec<PrivateParticipationClaim>>
Retrieves the calling agent's participation claims.
Privacy: Only returns claims owned by the calling agent Filtering: Optional filtering by claim type, time period, counterparty Use Case: Agent's reputation portfolio and history
derive_reputation_summary(input: DeriveReputationSummaryInput) -> ExternResult<ReputationSummary>
Derives a privacy-preserving reputation summary from participation claims.
Input:
#![allow(unused)] fn main() { pub struct DeriveReputationSummaryInput { pub period_start: Timestamp, pub period_end: Timestamp, pub include_categories: Option<Vec<String>>, // Optional category filtering } }
Business Logic:
- Calculates weighted average performance scores
- Categorizes claims by type
- Generates privacy-preserving summary
- Supports time-period based analysis
Privacy: Can be shared without revealing individual claim details
Private Data Validation
request_agent_validation_data(input: AgentValidationInput) -> ExternResult<ValidationResult>
Requests private data validation for agent validation workflows.
Input:
#![allow(unused)] fn main() { pub struct AgentValidationInput { pub agent_to_validate: AgentPubKey, pub validation_type: String, pub requesting_validator: AgentPubKey, pub validation_context: ActionHash, } }
Business Logic:
- Cross-zome call to person zome for private data access
- Validates specific data requirements based on validation type
- Creates validation receipt for audit trail
- Respects privacy and consent requirements
create_validation_with_private_data(input: CreateValidationWithPrivateDataInput) -> ExternResult<Record>
Creates validation with explicit private data access.
Privacy: Requires explicit consent for private data access Security: Creates audit trail of private data access Compliance: Ensures privacy requirements are met
NDO Federation Extensions
Added in PR #103. These three coordinator modules implement the NDO-to-NDO hard links,
peer-validated contributions, and benefit redistribution agreements specified in
documentation/requirements/post-mvp/lobby-dna.md (REQ-NDO-EXT-01–16).
Hard Links (hard_link.rs)
create_ndo_hard_link(input: CreateNdoHardLinkInput) -> ExternResult<ActionHash>
Creates a permanent, immutable OVN-licensed structural link between two NDOs.
The link is backed by a real EconomicEvent (its hash is stored and verified at creation time).
Input:
#![allow(unused)] fn main() { pub struct CreateNdoHardLinkInput { pub from_ndo_identity_hash: ActionHash, pub to_ndo_dna_hash: DnaHash, pub to_ndo_identity_hash: ActionHash, pub link_type: NdoLinkType, // Component | DerivedFrom | Supersedes pub fulfillment_hash: ActionHash, // must resolve to a record in this DHT } }
Business Logic:
- Verifies
fulfillment_hashresolves to an existing record - Creates a
NdoHardLinkentry (immutable, undeletable per OVN license requirement) - Creates
NdoToHardLinksanchor fromfrom_ndo_identity_hashfor global discovery - Creates
HardLinkByTypeanchor fromPath("ndo.hardlink.{type}")for filtered queries
get_ndo_hard_links(ndo_identity_hash: ActionHash) -> ExternResult<Vec<NdoHardLinkRecord>>
Returns all hard links originating from a given NDO identity hash. Resolves the latest update of each entry before returning.
get_ndo_hard_links_by_type(input: GetNdoHardLinksByTypeInput) -> ExternResult<Vec<NdoHardLinkRecord>>
Returns hard links filtered by NdoLinkType. Calls get_ndo_hard_links internally and filters client-side.
Input:
#![allow(unused)] fn main() { pub struct GetNdoHardLinksByTypeInput { pub ndo_identity_hash: ActionHash, pub link_type: NdoLinkType, } }
Contributions (contribution.rs)
validate_contribution(input: ValidateContributionInput) -> ExternResult<ActionHash>
Records and peer-validates a work contribution on an NDO. The calling agent is recorded
as the first validator in validated_by. The action field is constrained to
Work | Modify | Cite by integrity validation.
Input:
#![allow(unused)] fn main() { pub struct ValidateContributionInput { pub provider: AgentPubKey, pub action: VfAction, // Must be Work, Modify, or Cite pub work_log_group_dna_hash: Option<DnaHash>, pub work_log_action_hash: Option<ActionHash>, pub ndo_identity_hash: ActionHash, pub input_of: Option<ActionHash>, pub note: String, pub effort_quantity: Option<f64>, // hours [0.0, 10000.0] pub fulfills: Option<ActionHash>, pub has_point_in_time: Timestamp, } }
Business Logic:
- Creates a
Contributionentry with the calling agent asvalidated_by[0] - Creates
NdoToContributionsanchor fromndo_identity_hash - Creates
AgentToContributionsanchor frominput.provider(not the validator)
get_ndo_contributions(ndo_identity_hash: ActionHash) -> ExternResult<Vec<ContributionRecord>>
Returns all contributions for a given NDO identity hash via the NdoToContributions anchor.
get_agent_contributions(provider: AgentPubKey) -> ExternResult<Vec<ContributionRecord>>
Returns all contributions from a given agent (provider) via the AgentToContributions anchor.
Agreements (agreement.rs)
create_agreement(input: CreateAgreementInput) -> ExternResult<ActionHash>
Creates the first benefit redistribution Agreement (version 1) for an NDO.
Agreements are versioned (monotonic), undeletable, and linked to the NDO identity hash.
Input:
#![allow(unused)] fn main() { pub struct CreateAgreementInput { pub ndo_identity_hash: ActionHash, pub clauses: Vec<BenefitClause>, pub primary_accountable: Vec<AgentPubKey>, } }
Integrity validation:
primary_accountablemust be non-empty- Each
clause.share_percentmust be in[0.0, 100.0] - Sum of all
share_percentvalues must not exceed100.0
update_agreement(input: UpdateAgreementInput) -> ExternResult<ActionHash>
Updates an existing Agreement, incrementing its version monotonically.
Creates an AgreementUpdates chain link from the previous hash to the new one.
Input:
#![allow(unused)] fn main() { pub struct UpdateAgreementInput { pub original_action_hash: ActionHash, pub clauses: Vec<BenefitClause>, pub primary_accountable: Vec<AgentPubKey>, } }
Integrity validation: version must equal previous.version + 1 (enforced by HDI).
get_current_agreement(ndo_identity_hash: ActionHash) -> ExternResult<Option<AgreementRecord>>
Returns the latest version of the Agreement for a given NDO by walking the
AgreementUpdates chain from the NdoToAgreement anchor.
Link Architecture
Economic Event Links
- AllEconomicEvents:
economic_events anchor -> event_hash- Global discovery - ResourceToEvents:
resource_hash -> event_hash- Resource history - AgentToEvents:
agent_pubkey -> event_hash- Agent participation - EventToPrivateParticipationClaims:
event_hash -> claim_hash- PPR generation
Commitment Links
- AllCommitments:
commitments anchor -> commitment_hash- Global discovery - CommitmentToClaims:
commitment_hash -> claim_hash- Fulfillment tracking - CommitmentToPrivateParticipationClaims:
commitment_hash -> claim_hash- PPR tracking
Validation Links
- AllValidationReceipts:
validation_receipts anchor -> receipt_hash- Global discovery - ValidatedItemToReceipt:
validated_item -> receipt_hash- Validation history - ResourceToValidation:
resource_hash -> validation_hash- Resource validation - AllResourceValidations:
resource_validations anchor -> validation_hash- Validation discovery
PPR System Links
- AgentToPrivateParticipationClaims:
agent_pubkey -> claim_hash- Agent PPR portfolio - EventToPrivateParticipationClaims:
event_hash -> claim_hash- Event to PPR mapping - CommitmentToPrivateParticipationClaims:
commitment_hash -> claim_hash- Commitment to PPR mapping - ResourceToPrivateParticipationClaims:
resource_hash -> claim_hash- Resource to PPR mapping
Signal Architecture
The Governance zome emits signals for real-time UI updates:
#![allow(unused)] fn main() { pub enum Signal { LinkCreated { action }, LinkDeleted { action }, EntryCreated { action }, EntryUpdated { action }, EntryDeleted { action }, } }
Real-time Updates: Enables UI reactivity to governance changes Cross-Zome Coordination: Supports complex workflows with other zomes
Error Handling
GovernanceError Types
GovernanceError is defined in crates/utils/src/errors.rs and imported by zome_gouvernance.
#![allow(unused)] fn main() { pub enum GovernanceError { ValidationReceiptNotFound(String), // Validation lookup failures EconomicEventNotFound(String), // Event lookup failures ResourceValidationNotFound(String), // Resource validation lookup failures CommitmentNotFound(String), // Commitment lookup failures NotAuthorizedValidator, // Authorization failures InsufficientCapability(String), // Capability level restrictions ValidationAlreadyExists(String), // Duplicate validation prevention InvalidValidationScheme(String), // Validation scheme validation SerializationError(String), // Data serialization issues EntryOperationFailed(String), // DHT operation failures LinkOperationFailed(String), // Link operation failures InvalidInput(String), // Input validation failures CrossZomeCallFailed(String), // Cross-zome communication failures } }
Pattern: Comprehensive error coverage with descriptive messages
Integration: Converts to WasmError for Holochain compatibility
Privacy and Security Model
Private Data Protection
- Private Participation Claims: Stored as private entries, owner-only access
- Performance Metrics: Only accessible to claim owner
- Signature Verification: Cryptographic proof without revealing private data
- Reputation Summaries: Privacy-preserving reputation sharing
Cryptographic Security
- Bilateral Signatures: Both parties authenticate each interaction
- Tamper Evidence: Cryptographic hashes prevent undetected modifications
- Non-Repudiation: Agents cannot deny their participation in interactions
- Verification Support: Complete context for signature verification
Access Control
- Role-Based Access: Different functions require different capability levels
- Cross-Zome Validation: Private data access requires explicit validation
- Context-Aware Permissions: Access granted based on specific contexts and needs
- Audit Trails: Complete logging of all validation and access requests
Integration with Other Zomes
Resource Zome Integration
#![allow(unused)] fn main() { // Create economic event for resource custody transfer let event_output = call( CallTargetCell::Local, "zome_gouvernance", "log_economic_event".into(), None, &LogEconomicEventInput { action: VfAction::TransferCustody, provider: current_custodian, receiver: new_custodian, resource_inventoried_as: resource_hash, affects: resource_hash, resource_quantity: 1.0, note: Some("Custody transfer completed".to_string()), }, )?; }
Person Zome Integration
#![allow(unused)] fn main() { // Validate agent private data for promotion let validation_result = call( CallTargetCell::Local, "zome_gouvernance", "validate_agent_identity".into(), None, &ValidateAgentIdentityInput { agent: agent_to_validate, resource_hash: first_resource_hash, private_data_hash: Some(private_data_hash), }, )?; }
Implementation Status
✅ Completed Features
- Economic Event Logging: Complete ValueFlows-compliant economic event system
- Commitment Management: Full commitment lifecycle with claim tracking
- Validation System: Comprehensive validation workflows with receipt tracking
- PPR System: Complete Private Participation Receipt system with 16 claim types
- Reputation Management: Privacy-preserving reputation calculation and sharing
- Agent Validation: Comprehensive agent promotion and capability validation
- Cryptographic Security: Bilateral signatures and tamper-evident claims
- Private Data Protection: Secure private data validation workflows
- Cross-Zome Integration: Full integration with person and resource zomes
🔧 Current Limitations
- Basic Validation Schemes: Limited to simple approval, no complex multi-reviewer schemes
- No Economic Processes: Structured process workflows not implemented
- Limited Governance Rules: Basic rule enforcement without complex logic
- No Dispute Resolution: Structured dispute resolution workflows not implemented
📋 Future Enhancement Opportunities
- Advanced Validation Schemes: Implementation of 2-of-3, N-of-M, weighted voting
- Economic Process Integration: Structured workflows for Use, Transport, Storage, Repair
- Dispute Resolution System: Formal dispute resolution with mediator selection
- Smart Contract Integration: Automated rule enforcement and trigger conditions
- Reputation Analytics: Advanced reputation analysis and prediction
- Multi-Network Reputation: Cross-network reputation portability and validation
TODO (post-MVP — configurable GovernanceProcess, governance.md §6.2): Economic Process types (Use, Transport, Storage, Repair) are currently hardcoded strings. Post-MVP, introduce a
GovernanceProcessentry type so communities can define custom process types with their own role requirements, validation schemes, and operational state transitions. The current four process types become default instances, not compile-time constants.TODO (post-MVP — temporal governance, governance.md §4.8): Extend
GovernanceRulewith an optionalexpires_at: Timestampfield. The governance evaluation engine must skip expired rules duringevaluate_transition. Enables sunset clauses, seasonal access, and time-limited governance experiments.TODO (post-MVP — governance weight dampening, governance.md §6.4): When
governance_weight(agent)incorporatesunyt_credit_capacity, apply logarithmic dampening (e.g.,log(1 + credit_capacity)) to prevent a feedback loop where high reputation → high credit → higher governance weight → even higher reputation.
The Governance zome provides the foundational economic coordination infrastructure for the nondominium ecosystem, enabling ValueFlows-compliant resource sharing with comprehensive validation, cryptographically-secured reputation tracking, and sophisticated governance workflows.
Post-MVP Governance Architecture Gaps
The following TODOs summarise all governance-related post-MVP structural changes identified across
governance.md, agent.md, and the requirements suite. Use these as the canonical cross-reference
index when implementing each phase.
| Gap ID | Description | Affected Field(s) | Requirement(s) | governance.md ref |
|---|---|---|---|---|
| G1 | Collective/Bot agent governance | ValidationReceipt.validator, EconomicEvent.provider/receiver, Commitment.provider/receiver, PrivateParticipationClaim.counterparty, GovernanceTransitionRequest.requesting_agent, ResourceStateChange.initiated_by | REQ-GOV-16 | §3.6.1, §6.6 |
| G2 | AffiliationState governance gate | GovernanceRule.rule_data["min_affiliation"]; governance evaluate_transition | REQ-GOV-14 | §3.6.2, §6.4 |
| G6 | AffiliationRecord ceremony | New create_affiliation_record() + AffiliationRecordSigned PPR claim type | REQ-GOV-15 | §3.6.3, §4.4 |
| G9 | Sybil resistance for governance | Role promotion: N-of-M vouching or proof-of-personhood | REQ-GOV-17 | §5.3 |
| G10 | Pseudonymous governance participation | Pseudonymous path to ActiveAffiliate; block from legal-accountability roles | REQ-GOV-18 | §5.3 |
| G11 | Bot governance scope | Bot participation limited to declared capabilities; operator is accountable | — | §6.6 |
All fields marked with
TODO (G1, REQ-GOV-16)inline above must be migrated toAgentContextin Phase 3 of the implementation plan. Seeimplementation_plan.md §Phase 3 — Governance Agent Ontology Integrationfor detailed checklists.