# ExampleStore Public API

## By Wolf McNally, Blockchain Commons

`ExampleStore` is an implementation of a skeletal share store, which is a service that could be used to back up SSKR shares and similar non-confidential information that might be used for social recovery schemes.

This is the Swift interface of the `ExampleStore` public API; it is primarily called indirectly by the distributed function call API (forthcoming) which handles authentication of the public keys on incoming requests. So by the time any of these functions are called, the caller must have already proved by signature that they control the corresponding private key.

public protocol ExampleStoreProtocol {
    /// This is a Trust-On-First-Use (TOFU) function. If the provided public key is not
    /// recognized, then a new account is created and the provided payload is stored in
    /// it. It is also used to add additional shares to an existing account. Adding an
    /// already existing share to an account is idempotent.
    func storeShare(publicKey: PublicKeyBase, payload: Data) throws -> Receipt
    
    /// Updates an account's fallback contact method, which could be a phone
    /// number, email address, or similar. The fallback is used to give users a way to
    /// change their public key in the event they lose it. It is up to ExampleStore's
    /// owner to validate the fallback contact method before letting the public key be
    /// changed.
    func updateFallback(publicKey: PublicKeyBase, fallback: String?) throws

    /// Retrieves an account's fallback contact method, if any.
    func retrieveFallback(publicKey: PublicKeyBase) throws -> String?
    
    /// Changes the public key used as the account identifier. It could be invoked
    /// specifically because a user requests it, in which case they will need to know
    /// their old public key, or it could be invoked because they used their fallback
    /// contact method to request a transfer token that encodes their old public key.
    func updatePublicKey(old: PublicKeyBase, new: PublicKeyBase) throws

    /// Deletes either a subset of shares a user controls, or all the shares if a
    /// subset of receipts is not provided. Deletes are idempotent; in other words,
    /// deleting nonexistent shares is not an error.
    func deleteShares(publicKey: PublicKeyBase, receipts: Set<Receipt>?) throws

    /// Returns a dictionary of `[Receipt: Payload]` corresponding to the set of
    /// input receipts, or corresponding to all the controlled shares if no input
    /// receipts are provided. Attempting to retrieve nonexistent receipts or receipts
    /// from the wrong account is an error.
    func retrieveShares(publicKey: PublicKeyBase, receipts: Set<Receipt>?) throws -> [Receipt: Data]
    
    /// Deletes all the shares of an account and any other data associated with it, such
    /// as the fallback contact method. Deleting an account is idempotent; in other words,
    /// deleting a nonexistent account is not an error.
    func deleteAccount(publicKey: PublicKeyBase)
}