p2panda-core 0.8.0

Extensible data-types for secure, distributed and efficient exchange of data
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

// SPDX-License-Identifier: MIT OR Apache-2.0tra

//! Traits expressing core features of peer-to-peer data types.
use std::fmt::{Debug, Display};
use std::hash::Hash as StdHash;

use serde::{Deserialize, Serialize};

use crate::logs::SeqNum;
use crate::operation::{Body, PayloadSize};

/// Identifier of an operation author.
pub trait Author:
    Copy
    + Clone
    + Display
    + Debug
    + PartialEq
    + Eq
    + Ord
    + StdHash
    + Serialize
    + for<'de> Deserialize<'de>
{
}

/// Identifier of a single operation.
pub trait OperationId: Copy + Clone + Display + Debug + PartialEq + Eq + Ord + StdHash {}

#[cfg(any(test, feature = "test_utils"))]
impl OperationId for u32 {}
#[cfg(any(test, feature = "test_utils"))]
impl OperationId for &str {}

/// Returns (unique) hash digest, which can be used as identifier of this published data type.
pub trait Digest<ID>
where
    ID: OperationId,
{
    /// Hash digest of peer-to-peer data-type which can be used as the identifier.
    fn hash(&self) -> ID;
}

/// Returns the author of this published data type and a method to verify the authenticity of it.
pub trait Provenance<A>
where
    A: Author,
{
    /// Identity of the author of data-type.
    fn author(&self) -> A;

    /// Checks if data-type and given author is authentic.
    fn verify(&self) -> bool;
}

/// Hash-chain structure with integrity guarantees and sequence numbers as a performance
/// optimization.
pub trait Chain<ID> {
    /// Pointer at previous entry in log which gives us the integrity guarantee of the "hash chain".
    /// The first entry in a log returns `None`.
    fn backlink(&self) -> Option<ID>;

    /// Sequence numbers are helpful to fastly detect forks and use the much faster and optimized
    /// diffing strategy when the local log is not forked.
    fn seq_num(&self) -> SeqNum;
}

/// Additional data which can be removed from the on-chain data-type.
pub trait Offchain<ID> {
    /// Authenticated payload.
    ///
    /// Can be requested or removed independently from the peer-to-peer data-type (off-chain). Don't
    /// expect this to always be available.
    fn payload(&self) -> Option<&Body>;

    /// Hash digest of the payload.
    fn payload_hash(&self) -> Option<ID>;

    /// Size in bytes of the payload.
    fn payload_size(&self) -> PayloadSize;
}

/// Custom header extensions type.
///
/// User-defined extensions can be added to an operation's [`Header`](crate::Header) in order to
/// extend the basic functionality of the core p2panda data types or to encode application-specific
/// fields which should not be contained in the [`Body`].
///
/// This might be system-specific information relating to capabilities or key-agreement schemes
/// which is required to enforce access-control restrictions during sync. Alternatively, extensions
/// might be used to set expiration timestamps and deletion flags in order to facilitate garbage
/// collection of stale data from the network. The core p2panda data types intentionally don't
/// enforce a single approach to such areas where there are rightly many different approaches, with
/// the most suitable being dependent on specific use-case requirements.
///
/// Interfaces which use p2panda core data types can require certain extensions to be present on any
/// headers that their APIs accept using trait bounds. `p2panda-stream`, for example, uses the
/// [`PruneFlag`](crate::PruneFlag) in order to implement automatic network-wide garbage collection.
///
/// Extensions are encoded on a header and sent over the wire. We need to satisfy all trait
/// requirements that `Header` requires, including `Serialize` and `Deserialize`.
///
/// ## Example
///
/// ```
/// use p2panda_core::{Hash, Header, SigningKey};
/// use serde::{Serialize, Deserialize};
///
/// #[derive(Clone, Debug, Serialize, Deserialize)]
/// struct LogId(Hash);
///
/// #[derive(Clone, Debug, Serialize, Deserialize)]
/// struct CustomExtensions {
///     log_id: Option<LogId>,
///     expires: u64,
/// }
///
/// let extensions = CustomExtensions {
///     log_id: None,
///     expires: 1787246796,
/// };
///
/// let signing_key = SigningKey::generate();
///
/// let header = Header::builder()
///     .body("Hello, Sloth".as_bytes())
///     .build(&signing_key, extensions.clone());
///
/// assert_eq!(header.extensions.expires, 1787246796);
/// ```
pub trait Extensions: Clone + Debug + for<'de> Deserialize<'de> + Serialize {}

impl<T> Extensions for T where T: Clone + Debug + for<'de> Deserialize<'de> + Serialize {}

/// Returns a displayable string representing the underlying value in a short format, easy to read
/// during debugging and logging.
pub trait ShortFormat {
    fn fmt_short(&self) -> String;
}