rvf - Rust ValueFlows Implementation

Rust implementation of the ValueFlows vocabulary for distributed economic networks.

ValueFlows is a vocabulary for the distributed economic networks of the next economy, designed to coordinate the creation, distribution, and exchange of economic resources. It's based on the REA (Resources, Events, Agents) ontology.

Features

• Complete ValueFlows Implementation: All core types including Agents, Resources, Events, Commitments, Intents, Processes, Transfers, Exchanges, Plans, Proposals, and Recipes
• Production Ready: Comprehensive error handling, extensive test coverage, and proper documentation
• Serialization: Full serde support for JSON and other formats
• Storage Abstraction: Pluggable storage backends with an in-memory implementation included
• Type Safety: Leverages Rust's type system to prevent invalid states
• P2P Ready: All types are serializable and designed for distributed systems

Installation

Add to your Cargo.toml:

[dependencies]
rvf = "0.1"

Or with specific features:

[dependencies]
rvf = { version = "0.1", features = ["full"] }

Features Flags

• serde (default): Enable serialization/deserialization support
• uuid (default): Enable UUID generation for identifiers
• async: Enable async support for storage backends
• full: Enable all features

Quick Start

use rvf::prelude::*;

// Create an agent (person, organization, or ecological agent)
let farmer = Agent::builder()
    .id("agent-001")
    .name("Local Farm")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

// Create a resource specification (template/type of resource)
let tomato_spec = ResourceSpecification::builder()
    .id("spec-001")
    .name("Organic Tomatoes")
    .build()
    .unwrap();

// Create an economic resource
let tomatoes = EconomicResource::builder()
    .id("resource-001")
    .name("Farm Tomatoes Batch #1")
    .conforms_to(tomato_spec.id.clone())
    .primary_accountable(farmer.id.clone())
    .accounting_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

Core Concepts

Three Layers

ValueFlows operates in three layers:

1. Knowledge Layer (Recipes): Templates and patterns for economic activity
2. Plan Layer (Intents & Commitments): Offers, requests, and promises
3. Observation Layer (Events): Records of what actually happened

Key Types

Agents

Economic actors - people, organizations, or ecological agents.

let person = Agent::builder()
    .id("person-001")
    .name("Alice")
    .agent_type(AgentType::Person)
    .build()
    .unwrap();

Resources

Economic resources that can be created, transferred, or consumed.

let resource = EconomicResource::builder()
    .id("resource-001")
    .name("Wheat")
    .accounting_quantity(Measure::new(1000, Unit::Kilogram))
    .build()
    .unwrap();

Actions

Define what a flow does. Available actions:

• Production: Produce, Consume, Use, Cite
• Work: Work
• Transportation: Pickup, Dropoff
• Modification: Accept, Modify, Combine, Separate
• Transfer: Transfer, TransferAllRights, TransferCustody, Move
• Digital: Copy
• Adjustment: Raise, Lower
• Service: DeliverService

Events

Immutable records of economic activity.

let event = EconomicEvent::builder()
    .id("event-001")
    .action(ActionType::Produce)
    .provider("farmer-001")
    .receiver("farmer-001")
    .resource_inventoried_as("wheat-001")
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

Commitments

Promises for future events.

let commitment = Commitment::builder()
    .id("commitment-001")
    .action(ActionType::Transfer)
    .provider("seller-001")
    .receiver("buyer-001")
    .resource_quantity(Measure::new(50, Unit::Each))
    .build()
    .unwrap();

Intents

Offers and requests that may lead to commitments.

// An offer (I want to give)
let offer = Intent::offer()
    .id("offer-001")
    .provider("seller-001")
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(10, Unit::Each))
    .build()
    .unwrap();

// A request (I want to receive)
let request = Intent::request()
    .id("request-001")
    .receiver("buyer-001")
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(10, Unit::Each))
    .build()
    .unwrap();

// Check if intents match
if offer.matches(&request) {
    println!("These intents are compatible!");
}

Processes

Transformations that take inputs and produce outputs.

let process = Process::builder()
    .id("process-001")
    .name("Bread Baking")
    .build()
    .unwrap();

Transfers

Movement of resources between agents.

let transfer = Transfer::builder()
    .id("transfer-001")
    .name("Wheat Sale")
    .transfer_type(TransferType::Both) // Rights + Custody
    .provider("seller-001")
    .receiver("buyer-001")
    .build()
    .unwrap();

Exchanges

Reciprocal transfers between parties.

let exchange = Exchange::builder()
    .id("exchange-001")
    .name("Wheat for Money")
    .build()
    .unwrap();

Storage

The library provides a storage abstraction for persistence:

use rvf::storage::{Repository, InMemoryStorage, Storage};

// Create an in-memory repository
let repo = Repository::<Agent>::in_memory();

// Store an agent
repo.put("agent-001", agent.clone()).unwrap();

// Retrieve an agent
let retrieved = repo.get("agent-001").unwrap();

// Or use get_required which returns an error if not found
let agent = repo.get_required("agent-001").unwrap();

Production Workflow Example

use rvf::prelude::*;

// 1. Define the participants
let farm = Agent::builder()
    .id("farm-001")
    .name("Happy Valley Farm")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

let bakery = Agent::builder()
    .id("bakery-001")
    .name("Village Bakery")
    .agent_type(AgentType::Organization)
    .build()
    .unwrap();

// 2. Farm creates a wheat production process
let mut harvest = Process::builder()
    .id("process-001")
    .name("Wheat Harvest 2024")
    .build()
    .unwrap();

harvest.start();

// 3. Record the production event
let production = EconomicEvent::builder()
    .id("event-001")
    .action(ActionType::Produce)
    .provider(&farm.id)
    .receiver(&farm.id)
    .output_of(&harvest.id)
    .resource_quantity(Measure::new(1000, Unit::Kilogram))
    .build()
    .unwrap();

harvest.complete();

// 4. Farm publishes an offer
let offer = Intent::offer()
    .id("intent-001")
    .provider(&farm.id)
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 5. Bakery makes a matching request
let request = Intent::request()
    .id("intent-002")
    .receiver(&bakery.id)
    .action(ActionType::Transfer)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 6. Create a commitment when they agree
let mut commitment = Commitment::builder()
    .id("commitment-001")
    .action(ActionType::Transfer)
    .provider(&farm.id)
    .receiver(&bakery.id)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .build()
    .unwrap();

// 7. Record the actual transfer
let transfer_event = EconomicEvent::builder()
    .id("event-002")
    .action(ActionType::Transfer)
    .provider(&farm.id)
    .receiver(&bakery.id)
    .resource_quantity(Measure::new(100, Unit::Kilogram))
    .fulfills(&commitment.id)
    .build()
    .unwrap();

// 8. Mark commitment as fulfilled
commitment.fulfill(Measure::new(100, Unit::Kilogram));
assert!(commitment.is_finished());

Architecture Notes

P2P Integration

All types implement Clone, Debug, and optionally Serialize/Deserialize, making them suitable for:

• Content-addressable storage (CAS)
• Distributed hash tables (DHT)
• Blockchain/DLT systems
• Event sourcing architectures

Extensibility

The library is designed to be extended:

• Implement custom Storage backends for your persistence layer
• Add additional metadata through the note and in_scope_of fields
• Use the Identifiable trait for automatic ID extraction

Examples

Run the included examples to see ValueFlows in action:

# Farm-to-bakery economic exchange
cargo run --example farm_to_bakery

# AI agent collaboration for research report production
cargo run --example ai_agent_collaboration

See examples/README.md for detailed documentation, flow diagrams, and comparisons.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

References

• ValueFlows Specification
• REA Ontology
• ValueFlows GitHub