# API

## low lvl

### Assumptions

- business process is intentionally exposed to the consumer, so that the consumer might decide how to adopt it (ie. communication considerations)
- based upon it an intermediate API's might be constructed that are higher lvl and encapsulate business process details
- low lvl functions are either idempotent or don't have side effects (ie. communication)

### API

let event = ctl.incept(pk, wit);

// save message in not fully witnessed db
let id = ctl.finalize_incept(event, cb.sign(event));

let id_ctl = IdentifierController::new(id, ctl);

// publish all not fully witnessed events
if id_ctl.notify_witnesses() == Ok(0) {return};

// generate query for every witness
let query = id_ctl.query_mailbox(id_ctl.id, [wit_id]);

for q in query {
    // add to unpublished db while processing
    id_ctl.finalize_mailbox_query(q, cb.sign(q));
}

// publish all from unpublished db
id_ctl.broadcast_receipts();

- `incept -> Payload`
- `finalizeIncept -> Identifier`
- `publish()/notify_witnesses() -> Result<()>` -- publish everything what is in not fully witnessed escrow
- `queryMailbox -> Vec<Payload>` (one per witness)
- `finalizeQuery -> Result<()>`
- `c.broadcast_receipts()` -- add place for what was published (collection of digests)

## high lvl?

- `createWitnessedIdentifier()`
- `finalizeWitnessedIdentifier()`
- `createPrivateIdentifier()`
- `finalizePrivateIdentifier()`

# Test with controller and two witnesses

participant Controller as C
participant Witness1 as W1
participant Witness2 as W2

C -> C: Incept with witnesses and threshold 2 and sign
C-> W1: Publish event
C-> W2: Publish event
C -> W1: Query mailbox
C -> W2: Query mailbox
W1 -> C: Receipt from mailbox
C -> C: Process receipt
C -> C: Check (controller.get_state(controller_id)==None)if own inception was accepted. It shouldn't, not enough witness receipts. 
W2 -> C: Receipt from mailbox
C -> C: Process receipt
C -> C: Check (controller.get_state(controller_id)== Some(_)) if own inception was accepted. It should, witness threshold should be met.
C -> W1: Provide all receipts to witness. (Should happend automagically when event was accepted to kel)
C -> W2: Provide all receipts to witness
W1 -> W1: Check if witness has all receipts
W2 -> W2: Check if witness has all receipts