Struct sn_dbc::Dbc

pub struct Dbc {
    pub content: DbcContent,
    pub transaction: RingCtTransaction,
    pub spent_proofs: BTreeSet<SpentProof>,
}

Represents a Digital Bearer Certificate (Dbc).

A Dbc may be owned or bearer.

An owned Dbc is like a check. Only the recipient can spend it. A bearer Dbc is like cash. Anyone in possession of it can spend it.

An owned Dbc includes a PublicKey representing the Owner. A bearer Dbc includes a SecretKey representing the Owner.

An Owner consists of either a SecretKey (with implicit PublicKey) or a PublicKey.

The included Owner is called an Owner Base. The public key can be given out to multiple parties and thus multiple Dbc can share the same Owner Base.

The Spentbook never sees the Owner Base. Instead, when a transaction Output is created for a given Owner Base, a random derivation index is generated and used to derive a one-time-use Owner Once.

The Owner Once is used for a single transaction only and must be unique within the transaction as well as globally for the output DBC’s to be spendable.

Separate methods are available for Owned and Bearer DBCs.

To spend or work with an Owned Dbc, wallet software must obtain the corresponding SecretKey from the user, and then call an API function that accepts a SecretKey for the Owner Base.

To spend or work with a Bearer Dbc, wallet software can either:

1. use the bearer API methods that do not require a SecretKey, eg: dbc.amount_secrets_bearer()

– or –

2. obtain the Owner Base SecretKey from the Dbc and then call the Owner API methods that require a SecretKey. eg: dbc.amount_secrets(&dbc.dbc.owner_base().secret_key()?)

Sometimes the latter method can be better when working with mixed types of Dbcs. A useful pattern is to check up-front if the Dbc is bearer or not and obtain the SecretKey from the Dbc itself (bearer) or from the user (owned). Subsequent code is then the same for both types.

Fields

content: DbcContent

transaction: RingCtTransaction

spent_proofs: BTreeSet<SpentProof>

Implementations

impl Dbc

pub fn owner_base(&self) -> &Owner

pub fn owner_once(&self, base_sk: &SecretKey) -> Result<Owner>

returns derived one-time-use owner using SecretKey supplied by caller. will return an error if the supplied SecretKey does not match the Dbc owner’s public key.

pub fn owner_once_bearer(&self) -> Result<Owner>

returns derived one-time-use owner using SecretKey stored in bearer Dbc. will return an error if the SecretKey is not available. (not bearer)

pub fn derivation_index(&self, base_sk: &SecretKey) -> Result<DerivationIndex>

returns derivation index used to derive one-time-use keypair from owner base

pub fn derivation_index_bearer(&self) -> Result<DerivationIndex>

returns derivation index used to derive one-time-use keypair from owner base will return an error if the SecretKey is not available. (not bearer)

pub fn is_bearer(&self) -> bool

returns true if owner base includes a SecretKey.

If the SecretKey is present, this Dbc can be spent by anyone in possession of it, making it a true “Bearer” instrument.

If the SecretKey is not present, then only the person(s) holding the SecretKey matching the PublicKey can spend it.

pub fn amount_secrets(&self, base_sk: &SecretKey) -> Result<AmountSecrets>

decypts and returns the AmountSecrets

pub fn amount_secrets_bearer(&self) -> Result<AmountSecrets>

decypts and returns the AmountSecrets will return an error if the SecretKey is not available. (not bearer)

pub fn key_image(&self, base_sk: &SecretKey) -> Result<KeyImage>

returns KeyImage for the owner’s derived public key This is useful for checking if a Dbc has been spent.

pub fn key_image_bearer(&self) -> Result<KeyImage>

returns KeyImage for the owner’s derived public key This is useful for checking if a Dbc has been spent. will return an error if the SecretKey is not available. (not bearer)

pub fn as_true_input(&self, base_sk: &SecretKey) -> Result<TrueInput>

returns a TrueInput that represents this Dbc for use as a transaction input.

pub fn as_true_input_bearer(&self) -> Result<TrueInput>

returns a TrueInput that represents this Dbc for use as a transaction input. will return an error if the SecretKey is not available. (not bearer)

pub fn hash(&self) -> [u8; 32]

Generate hash of this DBC

pub fn verify<K: KeyManager>(
    &self,
    base_sk: &SecretKey,
    verifier: &K
) -> Result<(), Error>

Verifies that this Dbc is valid.

A Dbc recipient should call this immediately upon receipt.

important: this does not check if the Dbc has been spent. For that, one must query the SpentBook.

Note that the spentbook cannot perform this check. Only the Dbc recipient (private key holder) can.

see TransactionVerifier::verify() for a description of verifier requirements.

see comments for Dbc::verify_amount_matches_commitment() for a description of how to handle Error::AmountCommitmentsDoNotMatch

pub fn verify_bearer<K: KeyManager>(&self, verifier: &K) -> Result<(), Error>

bearer version of verify() will return an error if the SecretKey is not available. (not bearer)

pub fn to_bearer(&mut self, base_sk: &SecretKey) -> Result<(), Error>

Convert this instance from owned to bearer by supplying the secret key for the corresponding public key.

Will return an error if this instance is already bearer or if the supplied secret key doesn’t match the public key.

Trait Implementations

impl Clone for Dbc

fn clone(&self) -> Dbc

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dbc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.