Event streams

Every quid or title can have an append-only, monotonically-sequenced event stream, a tamper-evident audit log. It’s the protocol-level equivalent of an event bus with cryptographic integrity.

Shape

type EventTransaction struct {
    SubjectID   string                 // quid or title ID
    SubjectType string                 // "QUID" or "TITLE"
    Sequence    int64                  // monotonic per subject
    EventType   string                 // app-defined, e.g. "order.placed"
    Payload     map[string]interface{} // inline up to 64 KB
    PayloadCID  string                 // optional IPFS CID for larger payloads
}

• Sequence is monotonic per subject, not global, no cross-subject coordination required.
• EventType is free-form and app-defined. Pick names your team can search for in logs.
• Payloads above 64 KB go via IPFS with the CID recorded in the transaction so you keep on-chain bytes small.

Why events

Events are the right shape for:

• Audit trails, which user authorized this action, in this order, with these arguments.
• Supply chain, what stages has this artifact passed through, in order, signed by whom.
• State machines, the signed sequence of transitions for an entity’s lifecycle.

Signing and replay

Events are signed by the stream owner’s current epoch key. Because Sequence is monotonic per subject, replaying an event transaction produces a nonce conflict at the signer’s global ledger, see QDP-0001.

Large payloads

When a payload exceeds 64 KB, Quidnug expects an IPFS gateway configured via IPFS_ENABLED=true and IPFS_GATEWAY_URL=http://localhost:5001. The transaction records the CID; retrievers verify the CID matches the content before applying it.

Querying a stream

curl "http://localhost:8080/api/events?subjectId=alice&subjectType=QUID"

Returns events in sequence order with pagination. See the API reference for query parameters.