# APIv2 example steps CSP

This is an example document on how to use the Vocdoni APIv2 with the CSP as census validator.


---

### 1. Create an organization account

+ POST /account

{
    "address" : "0xabcde",
    "nonce" : "71621123"
}

+ POST /account/setOrganizationInfo

{
    "name": "Organization name",
    "description": "my-description",
    "header": "https://my/header.jpeg",
    "avatar": "https://my/avatar.png"
}

### 2. Create an election

+ POST /election

{
  "title": "Some important election title",
  "description": "Some important election description",
  "header": "https://its.my/header.jpeg",
  "streamUri": "https://youtu.be/1234",
  "startDate": "2022-09-10T11:20:53.769Z",
  "endDate": "2022-09-20T11:20:53.769Z",
  "voteType": {
        "encryptedVotes": true,
        "anonymous": false,
        "uniqueChoices": false,
        "maxVoteOverwrites": 1
  },
  "electionMode": {
        "autoStart": true,
        "interruptible": false,
        "dynamicCensus": false,
        "secretUntilTheEnd": false
  },
  "questions": [
    {
      "title": "Question 1",
      "description": "Description question 1",
      "choices": [
        "Yes",
        "No",
        "Abstain"
      ]
    },
    {
      "title": "Question 2",
      "description": "Description question 2",
      "choices": [
        "Yes",
        "No",
        "Maybe"
      ]
    }
  ],
  "census": {
    "type": "csp",
    "url": "https://csp.decidim.cat/api",
    "publicKey": "4b6e87d0b01c82cd269a57658c49ef2c429eaf4d480ca6710ff07af72c7059df"
  }
}

Census is the public key of the Credencials Service Provider (CSP).

**RESPONSE**

{
  "electionId": "21b2ea5345d2e0c941dd44ff4c43fc"
}

### 3. Retrive election information

+ GET /election/<electionID>

`GET /election/21b2ea5345d2e0c941dd44ff4c`

{
  "chainId": "vocdoni-main-1",
  "type": "blind-confidential-hidden-results",
  "organizationId": "20323909c3e0965d1489893db1512b32b55707ea",
  
  "title": "Some important election title",
  "description": "Some important election description",
  "header": "https://its.my/header.jpeg",
  "streamUri": "https://youtu.be/1234",
  "startDate": "2022-09-10T11:20:53.769Z",
  "endDate": "2022-09-20T11:20:53.769Z",
  "status": "waiting", // active, paused, ended, results
  "voteType": {
        "encryptedVotes": true,
        "anonymous": false,
        "uniqueChoices": false,
        "maxVoteOverwrites": 1
  },
  "electionMode": {
        "autoStart": true,
        "interruptible": false,
        "dynamicCensus": false,
        "secretUntilTheEnd": false
  },
  "questions": [
    {
      "title": "Question 1",
      "description": "Description question 1",
      "choices": [
        "Yes",
        "No",
        "Abstain"
      ]
    },
    {
      "title": "Question 2",
      "description": "Description question 2",
      "choices": [
        "Yes",
        "No",
        "Maybe"
      ]
    }
  ],

  "census": {
    "type": "csp",
    "url": "https://csp.decidim.org/api/auth",
    "publicKey": "4b6e87d0b01c82cd269a57658c49ef2c429eaf4d480ca6710ff07af72c7059df"
  }
    
  "voteCount": 0,
  "results": [],
}

---

### 4. Retrive CSP information

+ GET csp.decidim.cat/api

{
  "title": "Simple math challenge",
  "authType": "auth",
  "signatureType": [
    "blind",
    "ecdsa",
    "sharedkey"
  ],
  "authSteps": [
    {
      "title": "name",
      "type": "text"
    },
    {
      "title": "solution",
      "type": "int4"
    }
  ]
}

### 5. Authenticate with the CSP

#### Step 1

+ POST csp/api/<electionID>/<signatureType>/auth/<step>

`POST csp.decidim.cat/api/21b2ea5345d2e0c941dd44ff4c/blind/auth/0`

{
  "authData": [
    "John Smith"
  ]
}

**RESPONSE**

{
  "authToken": "9ba29669-3a38-43ac-a8f6-d6ac99d2e3a2",
  "response": [
    "123",
    "456"
  ]
}

#### Step 2

+ POST csp/api/<electionID>/<signaturetType>/auth/<step>

`POST csp.decidim.cat/api/21b2ea5345d2e0c941dd44ff4c/blind/auth/1`

{
  "authToken": "9ba29669-3a38-43ac-a8f6-d6ac99d2e3a2",
  "authData": [
    "579"
  ]
}

**RESPONSE**

{
      "token": "0d2347cf59313bdb4038f0c6643e9289d694c1c67d4d1d66f56968e374d48669"
}

### 6. Request the CSP blind signature

+ POST csp/api/<electionID>/<signatureType>/sign

`POST csp.decidim.cat/api/21b2ea5345d2e0c941dd44ff4c/blind/sign`

{
  "payload": "0x4a5e61c14cc275eec42a25f4a3d3d57b085eeedf459d5f9f9348a41a99e59dfa",
  "token": "0d2347cf59313bdb4038f0c6643e9289d694c1c67d4d1d66f56968e374d48669"
}

Payload is provided by the SDK.
It is constructed by using a cryptographic function that requires the voter public key certificate and the token provided by the CSP (last step). The payload is blinded, so the CSP cannot know what's the voter public key.

**RESPONSE**

{
  "signature": "0x4a5e61c14cc275eec42a25f4a3d3d57b085eeedf459d5f9f9348a41a99e59dfa"
}

The CSP signature over `payload` is unblinded by the voter and can be used as a census proof for sending the vote to the blockchain.

### 7. Vote

+ POST /vote

{
   "vote": "base64-string"
}

**RESPONSE**

{
    "voteId": "123452345234523452345",
    "txHash": "985746248234523412345"
}
  

The SDK provides the helpers for building the vote package.

Under the hood, these are the data structures composing a vote.

message VoteEnvelope {
	// Unique number per vote attempt, so that replay attacks can't reuse this payload
	bytes nonce = 1;
	// The process for which the vote is casted
	bytes electionId = 2;
	// Census proof (csp signature or other)
	Proof proof = 3; 
	// JSON string of the Vote Package (potentially encrypted), encoded as bytes.
	bytes votePackage = 4;
	// Hash of the private key + electionId
	bytes nullifier = 5;
	// On encrypted votes, contains the (sorted) indexes of the keys used to encrypt
	repeated uint32 encryptionKeyIndexes = 6;
}

{
    "votePackage": ["1","0"]
}

### 7. Check vote registration status

+ GET voteID/electionID/verify

`GET 123452345234523452345/21b2ea5345d2e0c941dd44ff4c43fc/verify`

HTTP 200