payload.rs (15593B)
1 use super::{ 2 CommerceError, 3 value::{check_lines, check_text}, 4 }; 5 use super::{FinalMeasurement, LineQuantity, Resolution}; 6 use crate::{ 7 AuthorityRef, FulfillmentGroupId, RecordId, Sequence, SourceId, Terms, TermsDigest, 8 UnixSeconds, Window, 9 }; 10 use alloc::{boxed::Box, string::String, vec::Vec}; 11 use core::fmt; 12 use zeroize::Zeroizing; 13 14 macro_rules! copy_getters { 15 ($($field:ident:$ty:ty),+ $(,)?)=> { $( 16 #[doc=concat!("Returns the explicit `",stringify!($field),"` claim without authenticating it.")] 17 pub const fn $field(&self)->$ty { self.$field } 18 )+ }; 19 } 20 macro_rules! simple { 21 ($name:ident,$doc:literal,{$($field:ident:$ty:ty),+ $(,)?})=> { 22 #[doc=$doc] 23 #[derive(Clone,Copy,Eq,PartialEq)] 24 pub struct $name { $($field:$ty),+ } 25 impl $name { 26 /// Captures already validated representations; references remain claims. 27 pub const fn new($($field:$ty),+)->Self { Self { $($field),+ } } 28 copy_getters!($($field:$ty),+); 29 } 30 }; 31 } 32 33 /// Complete seller quote data, without a hold, signature or buyer consent. 34 #[derive(Clone, Eq, PartialEq)] 35 pub struct TermsQuote { 36 terms: Box<Terms>, 37 expires_at: UnixSeconds, 38 in_reply_to: Option<SourceId>, 39 } 40 impl TermsQuote { 41 /// Captures complete values. Expiry actionability and any referenced chat or 42 /// record require independent source/time admission; no clock is observed. 43 pub fn new(terms: Terms, expires_at: UnixSeconds, in_reply_to: Option<SourceId>) -> Self { 44 Self { 45 terms: Box::new(terms), 46 expires_at, 47 in_reply_to, 48 } 49 } 50 /// Explicitly borrows the complete private terms claim. 51 pub const fn terms(&self) -> &Terms { 52 &self.terms 53 } 54 copy_getters!(expires_at:UnixSeconds,in_reply_to:Option<SourceId>); 55 } 56 /// Complete buyer request data, without authentication or stock effects. 57 #[derive(Clone, Eq, PartialEq)] 58 pub struct TermsRequest { 59 terms: Box<Terms>, 60 expires_at: UnixSeconds, 61 quote: Option<RecordId>, 62 } 63 impl TermsRequest { 64 /// Captures complete terms and an explicit optional quote reference. 65 pub fn new(terms: Terms, expires_at: UnixSeconds, quote: Option<RecordId>) -> Self { 66 Self { 67 terms: Box::new(terms), 68 expires_at, 69 quote, 70 } 71 } 72 /// Explicitly borrows the complete private terms claim. 73 pub const fn terms(&self) -> &Terms { 74 &self.terms 75 } 76 copy_getters!(expires_at:UnixSeconds,quote:Option<RecordId>); 77 } 78 /// A typed record target and bounded private reason. Its enclosing variant 79 /// identifies whether the target is a request, proposal or authorization. 80 #[derive(Clone, Eq, PartialEq)] 81 pub struct RecordReason { 82 target: RecordId, 83 reason: Zeroizing<String>, 84 } 85 impl RecordReason { 86 /// Bounds exact reason text before copying; target family needs admission. 87 pub fn new(target: RecordId, reason: &str) -> Result<Self, CommerceError> { 88 check_text(reason, 1024)?; 89 Ok(Self { 90 target, 91 reason: Zeroizing::new(reason.into()), 92 }) 93 } 94 copy_getters!(target:RecordId); 95 /// Explicitly borrows the private reason, without terminal/display escaping. 96 pub fn reason(&self) -> &str { 97 &self.reason 98 } 99 } 100 /// Complete proposed replacement terms, preserving the declared base reference. 101 #[derive(Clone, Eq, PartialEq)] 102 pub struct TermsProposal { 103 base_agreement: Option<RecordId>, 104 terms: Box<Terms>, 105 expires_at: UnixSeconds, 106 reason: Zeroizing<String>, 107 } 108 impl TermsProposal { 109 /// Bounds private text before capture. Consent and base-head admission are separate. 110 pub fn new( 111 base_agreement: Option<RecordId>, 112 terms: Terms, 113 expires_at: UnixSeconds, 114 reason: &str, 115 ) -> Result<Self, CommerceError> { 116 check_text(reason, 1024)?; 117 Ok(Self { 118 base_agreement, 119 terms: Box::new(terms), 120 expires_at, 121 reason: Zeroizing::new(reason.into()), 122 }) 123 } 124 copy_getters!(base_agreement:Option<RecordId>,expires_at:UnixSeconds); 125 /// Explicitly borrows complete private replacement terms. 126 pub const fn terms(&self) -> &Terms { 127 &self.terms 128 } 129 /// Explicitly borrows private proposal text. 130 pub fn reason(&self) -> &str { 131 &self.reason 132 } 133 } 134 simple!(TermsAuthorization,"A proposal/terms commitment claim, not participant consent.",{ 135 proposal:RecordId,terms_digest:TermsDigest,expires_at:UnixSeconds 136 }); 137 simple!(ProposalAuthorization,"A proposal/expiry claim whose counterparty must be independently verified.",{ 138 proposal:RecordId,expires_at:UnixSeconds 139 }); 140 141 /// Seller commitment data, without authenticated authority or installation. 142 #[derive(Clone, Copy, Eq, PartialEq)] 143 pub struct AgreementCommitment { 144 base_agreement: Option<RecordId>, 145 authorization: RecordId, 146 terms_digest: TermsDigest, 147 authority: AuthorityRef, 148 seller_sequence: Sequence, 149 } 150 impl AgreementCommitment { 151 /// Requires a positive seller sequence; all source/authority evidence is separate. 152 pub fn new( 153 base_agreement: Option<RecordId>, 154 authorization: RecordId, 155 terms_digest: TermsDigest, 156 authority: AuthorityRef, 157 seller_sequence: Sequence, 158 ) -> Result<Self, CommerceError> { 159 positive(seller_sequence)?; 160 Ok(Self { 161 base_agreement, 162 authorization, 163 terms_digest, 164 authority, 165 seller_sequence, 166 }) 167 } 168 copy_getters!(base_agreement:Option<RecordId>,authorization:RecordId,terms_digest:TermsDigest, 169 authority:AuthorityRef,seller_sequence:Sequence); 170 } 171 /// Serialized seller withdrawal-decision claim, without final race resolution. 172 #[derive(Clone, Copy, Eq, PartialEq)] 173 pub struct WithdrawalAcknowledgement { 174 withdrawal: RecordId, 175 seller_sequence: Sequence, 176 } 177 impl WithdrawalAcknowledgement { 178 /// Requires a positive explicit seller decision sequence. 179 pub fn new(withdrawal: RecordId, seller_sequence: Sequence) -> Result<Self, CommerceError> { 180 positive(seller_sequence)?; 181 Ok(Self { 182 withdrawal, 183 seller_sequence, 184 }) 185 } 186 copy_getters!(withdrawal:RecordId,seller_sequence:Sequence); 187 } 188 /// Bounded residual-cancellation proposal, without releasing any stock. 189 #[derive(Clone, Eq, PartialEq)] 190 pub struct CancellationProposal { 191 agreement: RecordId, 192 residual: Box<[LineQuantity]>, 193 reason: Zeroizing<String>, 194 expires_at: UnixSeconds, 195 } 196 impl CancellationProposal { 197 /// Requires one through32 distinct line assertions and bounded private text. 198 pub fn new( 199 agreement: RecordId, 200 residual: Vec<LineQuantity>, 201 reason: &str, 202 expires_at: UnixSeconds, 203 ) -> Result<Self, CommerceError> { 204 check_lines(&residual, 1)?; 205 check_text(reason, 1024)?; 206 Ok(Self { 207 agreement, 208 residual: residual.into_boxed_slice(), 209 reason: Zeroizing::new(reason.into()), 210 expires_at, 211 }) 212 } 213 copy_getters!(agreement:RecordId,expires_at:UnixSeconds); 214 /// Borrows exact proposed residual assertions, without assuming current residual. 215 pub fn residual(&self) -> &[LineQuantity] { 216 &self.residual 217 } 218 /// Explicitly borrows the private cancellation reason. 219 pub fn reason(&self) -> &str { 220 &self.reason 221 } 222 } 223 /// Complete seller residual-release claim; construction does not move stock. 224 #[derive(Clone, Eq, PartialEq)] 225 pub struct ResidualRelease { 226 proposal: RecordId, 227 authorization: RecordId, 228 agreement: RecordId, 229 residual: Box<[LineQuantity]>, 230 authority: AuthorityRef, 231 seller_sequence: Sequence, 232 } 233 impl ResidualRelease { 234 /// Bounds line data and requires a positive seller decision sequence. 235 pub fn new( 236 proposal: RecordId, 237 authorization: RecordId, 238 agreement: RecordId, 239 residual: Vec<LineQuantity>, 240 authority: AuthorityRef, 241 seller_sequence: Sequence, 242 ) -> Result<Self, CommerceError> { 243 check_lines(&residual, 1)?; 244 positive(seller_sequence)?; 245 Ok(Self { 246 proposal, 247 authorization, 248 agreement, 249 residual: residual.into_boxed_slice(), 250 authority, 251 seller_sequence, 252 }) 253 } 254 copy_getters!(proposal:RecordId,authorization:RecordId,agreement:RecordId,authority:AuthorityRef,seller_sequence:Sequence); 255 /// Borrows the complete declared release quantities, pending state/consent checks. 256 pub fn residual(&self) -> &[LineQuantity] { 257 &self.residual 258 } 259 } 260 /// A seller readiness assertion, without physical handover or buyer receipt. 261 #[derive(Clone, Eq, PartialEq)] 262 pub struct ReadinessClaim { 263 agreement: RecordId, 264 fulfillment_group: FulfillmentGroupId, 265 lines: Box<[LineQuantity]>, 266 window: Window, 267 } 268 impl ReadinessClaim { 269 /// Bounds exact declared lines; agreement/group membership needs admission. 270 pub fn new( 271 agreement: RecordId, 272 fulfillment_group: FulfillmentGroupId, 273 lines: Vec<LineQuantity>, 274 window: Window, 275 ) -> Result<Self, CommerceError> { 276 check_lines(&lines, 1)?; 277 Ok(Self { 278 agreement, 279 fulfillment_group, 280 lines: lines.into_boxed_slice(), 281 window, 282 }) 283 } 284 copy_getters!(agreement:RecordId,fulfillment_group:FulfillmentGroupId,window:Window); 285 /// Borrows complete asserted ready quantities. 286 pub fn lines(&self) -> &[LineQuantity] { 287 &self.lines 288 } 289 } 290 /// A seller handover/measurement assertion; it is not physical truth or consumption. 291 #[derive(Clone, Eq, PartialEq)] 292 pub struct HandoverClaim { 293 agreement: RecordId, 294 fulfillment_group: FulfillmentGroupId, 295 lines: Box<[LineQuantity]>, 296 measurements: Box<[FinalMeasurement]>, 297 occurred_at: UnixSeconds, 298 authority: AuthorityRef, 299 seller_sequence: Sequence, 300 } 301 impl HandoverClaim { 302 /// Bounds line/measurement data, rejects duplicate or unrelated measurement 303 /// line IDs and requires a positive seller decision sequence. Agreement 304 /// unit/range/economic/cumulative admission remains mandatory and separate. 305 pub fn new( 306 agreement: RecordId, 307 fulfillment_group: FulfillmentGroupId, 308 lines: Vec<LineQuantity>, 309 measurements: Vec<FinalMeasurement>, 310 occurred_at: UnixSeconds, 311 authority: AuthorityRef, 312 seller_sequence: Sequence, 313 ) -> Result<Self, CommerceError> { 314 check_lines(&lines, 1)?; 315 positive(seller_sequence)?; 316 if measurements.len() > 32 { 317 return Err(CommerceError::InvalidMeasurements); 318 } 319 for (index, measurement) in measurements.iter().enumerate() { 320 if !lines 321 .iter() 322 .any(|line| line.line_id() == measurement.line_id()) 323 || measurements[..index] 324 .iter() 325 .any(|prior| prior.line_id() == measurement.line_id()) 326 { 327 return Err(CommerceError::InvalidMeasurements); 328 } 329 } 330 Ok(Self { 331 agreement, 332 fulfillment_group, 333 lines: lines.into_boxed_slice(), 334 measurements: measurements.into_boxed_slice(), 335 occurred_at, 336 authority, 337 seller_sequence, 338 }) 339 } 340 copy_getters!(agreement:RecordId,fulfillment_group:FulfillmentGroupId,occurred_at:UnixSeconds, 341 authority:AuthorityRef,seller_sequence:Sequence); 342 /// Borrows complete seller quantity assertions. 343 pub fn lines(&self) -> &[LineQuantity] { 344 &self.lines 345 } 346 /// Borrows bounded final measurements, still requiring independent price/range checks. 347 pub fn measurements(&self) -> &[FinalMeasurement] { 348 &self.measurements 349 } 350 } 351 /// A buyer's independent observation, without seller stock consumption. 352 #[derive(Clone, Eq, PartialEq)] 353 pub struct ReceiptObservation { 354 handover: RecordId, 355 lines: Box<[LineQuantity]>, 356 supersedes: Option<RecordId>, 357 occurred_at: UnixSeconds, 358 note: Zeroizing<String>, 359 } 360 impl ReceiptObservation { 361 /// Bounds exact observations and private text. Zero observation remains 362 /// representable; it never becomes a positive movement or inferred release. 363 pub fn new( 364 handover: RecordId, 365 lines: Vec<LineQuantity>, 366 supersedes: Option<RecordId>, 367 occurred_at: UnixSeconds, 368 note: &str, 369 ) -> Result<Self, CommerceError> { 370 check_lines(&lines, 1)?; 371 check_text(note, 1024)?; 372 Ok(Self { 373 handover, 374 lines: lines.into_boxed_slice(), 375 supersedes, 376 occurred_at, 377 note: Zeroizing::new(note.into()), 378 }) 379 } 380 copy_getters!(handover:RecordId,supersedes:Option<RecordId>,occurred_at:UnixSeconds); 381 /// Borrows complete asserted observations; supersession is not accumulation. 382 pub fn lines(&self) -> &[LineQuantity] { 383 &self.lines 384 } 385 /// Explicitly borrows private receipt text. 386 pub fn note(&self) -> &str { 387 &self.note 388 } 389 } 390 /// A complete proposed issue resolution, not mutual authorization or installation. 391 #[derive(Clone, Eq, PartialEq)] 392 pub struct ResolutionProposal { 393 agreement: RecordId, 394 resolution: Resolution, 395 expires_at: UnixSeconds, 396 } 397 impl ResolutionProposal { 398 /// Captures bounded resolution data and explicit source/time claims. 399 pub const fn new(agreement: RecordId, resolution: Resolution, expires_at: UnixSeconds) -> Self { 400 Self { 401 agreement, 402 resolution, 403 expires_at, 404 } 405 } 406 copy_getters!(agreement:RecordId,expires_at:UnixSeconds); 407 /// Explicitly borrows complete private resolution data. 408 pub const fn resolution(&self) -> &Resolution { 409 &self.resolution 410 } 411 } 412 /// A seller resolution-commitment claim, without installed effects. 413 #[derive(Clone, Copy, Eq, PartialEq)] 414 pub struct ResolutionCommitment { 415 proposal: RecordId, 416 authorization: RecordId, 417 authority: AuthorityRef, 418 seller_sequence: Sequence, 419 } 420 impl ResolutionCommitment { 421 /// Requires a positive seller decision sequence; consent/authority need admission. 422 pub fn new( 423 proposal: RecordId, 424 authorization: RecordId, 425 authority: AuthorityRef, 426 seller_sequence: Sequence, 427 ) -> Result<Self, CommerceError> { 428 positive(seller_sequence)?; 429 Ok(Self { 430 proposal, 431 authorization, 432 authority, 433 seller_sequence, 434 }) 435 } 436 copy_getters!(proposal:RecordId,authorization:RecordId,authority:AuthorityRef,seller_sequence:Sequence); 437 } 438 fn positive(sequence: Sequence) -> Result<(), CommerceError> { 439 if sequence.get() == 0 { 440 return Err(CommerceError::InvalidSequence); 441 } 442 Ok(()) 443 } 444 macro_rules! redacted { 445 ($($name:ident),+)=> { $(impl fmt::Debug for $name { 446 fn fmt(&self,f:&mut fmt::Formatter<'_>)->fmt::Result { f.write_str(concat!(stringify!($name),"(<redacted>)")) } 447 })+ }; 448 } 449 redacted!( 450 TermsQuote, 451 TermsRequest, 452 RecordReason, 453 TermsProposal, 454 TermsAuthorization, 455 ProposalAuthorization, 456 AgreementCommitment, 457 WithdrawalAcknowledgement, 458 CancellationProposal, 459 ResidualRelease, 460 ReadinessClaim, 461 HandoverClaim, 462 ReceiptObservation, 463 ResolutionProposal, 464 ResolutionCommitment 465 );