Cloak Key Management API (0.1.1)

Download OpenAPI specification:Download

Cloak provides a simple key management API for BN254 key pairs. It allows users to create a key pair where the private key will only be revealed after a certain time. The time is determined by the conclusion of an auction that the key is mapped to based on observations of blockchain events.

Keys

Routes for creating keys and retrieving them when revealed

Create a new BN254 key pair. Returns the public key coordinates.

Responses

Local

http://localhost:8080/new_key_pair

Testnet

https://api-testnet-v3.up.railway.app/new_key_pair

Response samples

200

Content type

application/json

Retrieve the public key for a given lot ID.

path Parameters

lot_id

required

integer

The lot ID to retrive the public key for

header Parameters

x-chain-id required	integer The ID of a chain the auction is on
x-auction-house required	string The address of the auction house contract the auction is on

Responses

Local

http://localhost:8080/public_key/{lot_id}

Testnet

https://api-testnet-v3.up.railway.app/public_key/{lot_id}

Response samples

200

Content type

application/json

Retrieve the private key for a given lot ID. The private key will only be revealed after the auction for the lot has concluded. If an auction is cancelled, the private key will not be revealed.

path Parameters

lot_id

required

integer

The lot ID to retrive the private key for

header Parameters

x-chain-id required	integer The ID of a chain the auction is on
x-auction-house required	string The address of the auction house contract the auction is on

Responses

Local

http://localhost:8080/private_key/{lot_id}

Testnet

https://api-testnet-v3.up.railway.app/private_key/{lot_id}

Response samples

200

Content type

application/json

"string"

Encrypt a bid for a given lot ID. The bid will be encrypted using the public key for the lot and a randomized seed.

path Parameters

lot_id

required

integer

The lot ID to encrypt the bid for

header Parameters

x-chain-id required	integer The ID of a chain the auction is on
x-auction-house required	string The address of the auction house contract the auction is on

Request Body schema: application/json
required

The bid amount to encrypt

amount	string The bid amount in, used to calculate an encryption salt
amount_out	string The bid amount out to encrypt
bidder	string The bidder's address

Responses

Local

http://localhost:8080/encrypt/{lot_id}

Testnet

https://api-testnet-v3.up.railway.app/encrypt/{lot_id}

Request samples

Payload

Content type

application/json

{
                                  
                                    
                                      
                                        "amount":
                                        "string",
                                      
                                    
                                    
                                      
                                        "amount_out":
                                        "string",
                                      
                                    
                                    
                                      
                                        "bidder":
                                        "string"
                                      
                                    
                                  
                                  }

Response samples

200

Content type

application/json

{
                                  
                                    
                                      
                                        "ciphertext":
                                        "string",
                                      
                                    
                                    
                                      
                                        "x":
                                        "string",
                                      
                                    
                                    
                                      
                                        "y":
                                        "string"
                                      
                                    
                                  
                                  }

Retrieve optimal decrypts for the next N bids to be decrypted on the a given lot ID. Assumes that the key information for the auction was created by the service.

path Parameters

lot_id required	integer The lot ID to retrive hints for
num required	integer The number of hints to retrieve

header Parameters

x-chain-id required	integer The ID of a chain the auction is on
x-auction-house required	string The address of the auction house contract the auction is on

Responses

Local

http://localhost:8080/hints/{lot_id}/{num}

Testnet

https://api-testnet-v3.up.railway.app/hints/{lot_id}/{num}

Response samples

200

Content type

application/json

Retrieve optimal decrypts for the next N bids to be decrypted on the a given lot ID. Works for any lot ID, assuming the private key for the auction has been submitted to the contract.

path Parameters

lot_id required	integer The lot ID to retrive hints for
num required	integer The number of hints to retrieve

header Parameters

x-chain-id required	integer The ID of a chain the auction is on
x-auction-house required	string The address of the auction house contract the auction is on

Responses

Local

http://localhost:8080/hints/{lot_id}/{num}/external

Testnet

https://api-testnet-v3.up.railway.app/hints/{lot_id}/{num}/external

Response samples

200

Content type

application/json

Configs

Routes for viewing supported configurations

Gets all chain configurations supported by the API.

Responses

Local

http://localhost:8080/configs

Testnet

https://api-testnet-v3.up.railway.app/configs

Response samples

200

Content type

application/json

[
                                  
                                    
                                      
                                        {
                                        
                                          
                                            
                                              "chain_id":
                                              0,
                                            
                                          
                                          
                                            
                                              "auction_house":
                                              "string"
                                            
                                          
                                        
                                        }
                                      
                                    
                                  
                                  ]

Gets all supported configurations for the specified chain.

path Parameters

chain_id

required

integer

The chain ID to retrive the configurations for

Responses

Local

http://localhost:8080/configs/chain/{chain_id}

Testnet

https://api-testnet-v3.up.railway.app/configs/chain/{chain_id}

Response samples

200

Content type

application/json

[
                                  
                                    
                                      
                                        {
                                        
                                          
                                            
                                              "chain_id":
                                              0,
                                            
                                          
                                          
                                            
                                              "auction_house":
                                              "string"
                                            
                                          
                                        
                                        }
                                      
                                    
                                  
                                  ]

Gets the supported auction modules for the provided configuration.

header Parameters

x-chain-id required	integer The ID of a chain
x-auction-house required	string The address of the auction house contract the auction is on

Responses

Local

http://localhost:8080/configs/auction_modules

Testnet

https://api-testnet-v3.up.railway.app/configs/auction_modules

Response samples

200

Content type

application/json

Cloak Key Management API (0.1.1)

Keys

Create a new BN254 key pair. Returns the public key coordinates.

Responses

Response samples

Retrieve the public key for a given lot ID.

path Parameters

header Parameters

Responses

Response samples

Retrieve the private key for a given lot ID. The private key will only be revealed after the auction for the lot has concluded. If an auction is cancelled, the private key will not be revealed.

path Parameters

header Parameters

Responses

Response samples

Encrypt a bid for a given lot ID. The bid will be encrypted using the public key for the lot and a randomized seed.

path Parameters

header Parameters

Request Body schema: application/json required

Responses

Request samples

Response samples

Retrieve optimal decrypts for the next N bids to be decrypted on the a given lot ID. Assumes that the key information for the auction was created by the service.

path Parameters

header Parameters

Responses

Response samples

Retrieve optimal decrypts for the next N bids to be decrypted on the a given lot ID. Works for any lot ID, assuming the private key for the auction has been submitted to the contract.

path Parameters

header Parameters

Responses

Response samples

Configs

Gets all chain configurations supported by the API.

Responses

Response samples

Gets all supported configurations for the specified chain.

path Parameters

Responses

Response samples

Gets the supported auction modules for the provided configuration.

header Parameters

Responses

Response samples

Request Body schema: application/json
required