Communication protocol Alice's front <--> API backend

[Elli610]

Alice front and API communication

Global communication

sequenceDiagram
    participant Front
    participant API

    Front->>API: 1. Initiate ring signature: payload P0
    loop
      API->>API: 2. verify P0 data.
    end
    API->>Front: 3. accept or deny request: payload P1
    loop
      API->>API: 4. if request accepted, <br> start creating the ring
    end
  
    API->>Front: 5. send ring 
    loop
      Front->>Front: 6. start signing process
    end
    Front->>API: 7. ask for mint: payload P2

    loop
      API->>API: verify P2 data and mint the SBT
    end
    API->>Front: 9. accept or deny mint request: payload P3
    loop
      API->>API: 10. if signature accepted, <br> mint the SBT to prover address
    end

Loading

Ring generation

Once the payment is successful, the user initiates the signature process by sending a request to the API server. The API server will check the request and send a response to the front end. If the request is accepted, the API server will start the signing process. If the request is denied, the API server will send a message to the front end to explain why the request is denied.

sequenceDiagram
    participant Front
    participant API

    Front->>API: 1. Initiate ring signature: payload P0
    loop
      API->>API: 2. verify P0 data.
    end
    API->>Front: 3. accept or deny request: payload P1
    loop
      API->>API: 4. if request accepted, <br> start creating the ring
    end

    API->>Front: 5. send ring 
    loop
      Front->>Front: 6. start signing process
    end

Loading

Payloads:

• P0:

{
  "type": "ring_generation_init",
  "data": {
    "paymentId": "txHash",
    "sigData": {
      "ringSize": 1000,
      "curve": "ED25519",
      "minBalance": "1000000000000000000",
      "provingPublicKey": "publicKey",
      "currency": "ticker",
    }
  },
  "provingSignature": "signature",
}

note:

• paymentId is the transaction hash of the payment
• sigData is the data needed to initiate the ring signature
• ringSize is the number of participants in the ring signature
• curve is the curve used for the ring signature ('SECP256K1', 'ED25519') (only the name, do not send a curve object)
• minBalance is the minimum token balance of the participants in the ring signature (in the smallest unit)
• provingPublicKey is the base64Encoded public key of the user in order to verify the proving signature (type: Point)
• currency is the currency of the payment (token ticker)
• provingSignature is the signature of the payload P0Data signed by the user in order to prove that the user is the owner of the receiving address

P0Data:

{
  "paymentId": "txHash",
  "sigData": {
    "ringSize": 1000,
    "curve": "ED25519",
    "minXrpBalance": "1000000000000000000",
    "provingPublicKey": "publicKey",
    "currency": "ticker",
  }
}

P1:

{
  "type": "ring_signature_init_response",
  "data": {
    "status": true,
    "signatureId": "signatureId or undefined",
    "ring": "ring or undefined",
    "validAtBlock": 123456
  },
  "error": "error message or undefined",
}

note:

• status is the status of the request (true: accepted, false: denied)
• signatureId is the id of the signature (= the id of the payment)
• ring is undefined or a list of b64 encoded points separated by ","
• validAtBlock is the latest block before the ring was generated
• error is the error message (if an error happens on the API side)

Mint request

Once the frontend receives the response from the API server, it will start the signing process. Then, the frontend will send a request to the API server to ask for minting the SBT. The API server will check the request and send a response to the frontend. If the request is accepted, the API server will mint the SBT to the prover address. If the request is denied, the API server will send a message to the frontend to explain why the request is denied.

sequenceDiagram
    participant Front
    participant API

    Front->>API: 7. ask for mint: payload P2

    loop
      API->>API: verify P2 data and mint the SBT
    end

    API->>Front: 9. accept or deny mint request: payload P3

    loop
      API->>API: 10. if signature accepted, <br> mint the SBT to prover address
    end

Loading

Payloads:

P2:

{
  "type": "mint_request",
  "data": {
    "signatureId": "signatureId",
    "ringSignature": "b64 encoded ring signature",
    "signature": "signature",
  },
}

note:

• signatureId is the id of the signature (= the id of the payment)
• ringSignature is the ring signature (base64Encoded string)
• signature is the signature of the ring signature signed by the user (base64Encoded string) (this is generated by the prover's private key). signed data are: { signatureId: signatureId, ringSignature: ringSignature }

P3:

{
  "type": "mint_request_response",
  "data": {
    "signatureId": "signatureId",
    "isValid": true,
    "nftMintTx": "udefined or mint tx hash"
    "proofURI": "undefined or string"
    "error": "error message or undefined",
  },
}

note:

• signatureId is the id of the signature (= the id of the payment)
• isValid is the status of the signature (true: valid, false: invalid)
• error is the error message (if an error happens on the API side or to explain why the signature is invalid)