Zero Knowledge Token Transfer API (1.0)

Download OpenAPI specification:Download

With Kaleido's Zero Knowledge Token Transfer service, transfers are conducted with Zero Knowledge Proofs such that the transactions are both confidential (the balances and transfer amounts are concealed), and anonymous (the sender and receiver identities are concealed).

Currently the service supports shielding ERC20 tokens. Ethereum accounts holding balances in ERC20 tokens can use their tokens to fund a corresponding shielded account in the service, and obtain equal amount shielded tokens. They the shielded tokens can be transfers among the shielded accounts owned by the participating organizations.

Shielded token balances can be used to exchange back to ERC20 tokens by withdrawing.

This service is part of Kaleido Lab's experimental catalog. tokenzkp

Authentication

bearer_token

Kaleido API for platform resources are authenticated using the Bearer token in the Authorization HTTP header. The token can either be the API Key created in the Kaleido user's account, or the JWT token issued to the user's browser as a cookie after logging in. The JWT token is set to expire in one hour.

Security scheme type: HTTP
HTTP Authorization Scheme bearer

app_creds

Kaleido API for marketplace services are authenticated using application credentials. The username and password must be created in the environment containing the service instance as "Application Credentials". For more details see the documentation on App Credentials.

Security scheme type: HTTP
HTTP Authorization Scheme basic

Shielded Account

Get shielded and unshielded ethereum accounts

Returns the accounts owned by the current membership across all Zero Knowledge Token Transfer services, both unshielded Ethereum accounts and shielded accounts. If the entry contains an index property, they exist locally inside the target service instance, and can be used to send shielded tokens and query balances

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$

Responses

200

Accounts Retrieved

get /accounts

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/accounts

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "membership_id": "string",
  • "ethAccount": "string",
  • "shieldedAccount":
    [
    ],
  • "index": 0
}

Create shielded account

Create a shielded account for the Ethereum account, so that the new shielded account can be funded with the Ethereum account

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
Request Body schema: application/json
ethAccount
required
string^0x[0-9a-fA-F]{40}$

Responses

200

Shielded Account Created

post /accounts

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/accounts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ethAccount": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "membership_id": "string",
  • "ethAccount": "string",
  • "shieldedAccount":
    [
    ],
  • "index": 0
}

ZKP Contracts

Get Zero Knowledge Transfer contracts

Returns the Zero Knowledge Transfer contracts deployed in the environment along with their corresponding ERC20 contracts

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$

Responses

200

Contracts Retrieved

get /contracts

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Deploy Zero Knowledge Proof contract (ZSC)

Deploys a Zero Knowledge Proof contract (ZSC)

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
Request Body schema: application/json
erc20
required
string

ERC20 token contract address used by the ZSC for funding and withdrawing operations

Responses

201

Contract Created

post /contracts

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "erc20": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "zsc": "string",
  • "erc20": "string",
  • "epochLength": 0,
  • "compatible": true
}

Fund a shielded account

Funds a shielded account in a Zero Knowledge Proof contract (ZSC) by transfering ERC20 tokens to the ZSC contract

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
shielded_contract_id
required
string^0x[0-9a-f]{40}$
Request Body schema: application/json
ethAccount
required
string^0x[0-9a-fA-F]{40}$

The Ethereum account to receive the ERC20 tokens from the ZSC after burning equal amount of Zethers from the corresponding shielded account

amount
required
integer

The amount of ERC20 tokens to transfer

Responses

201

Funding Successful

post /contracts/{shielded_contract_id}/fund

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts/{shielded_contract_id}/fund

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ethAccount": "string",
  • "amount": 0
}

Withdraw balance from a shielded account

Withdraws from a shielded account in a Zero Knowledge Proof contract (ZSC) by burning the requested amount of Zether and transfering equal amount of ERC20 tokens back to the original funding account

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
shielded_contract_id
required
string^0x[0-9a-f]{40}$
Request Body schema: application/json
ethAccount
required
string^0x[0-9a-fA-F]{40}$

The Ethereum account to draw the ERC20 tokens from in order to fund the corresponding shielded account inside the ZSC

shieldedAccount
Array of strings

Optional. The shielded account corresponding to the Ethereum account.

amount
required
integer

The amount of ERC20 tokens to transfer

Responses

201

Withdraw Successful

post /contracts/{shielded_contract_id}/withdraw

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts/{shielded_contract_id}/withdraw

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "ethAccount": "string",
  • "shieldedAccount":
    [
    ],
  • "amount": 0
}

Transfer Zether tokens between shielded accounts

Transfers Zether tokens from a shielded account to another shielded account in a Zero Knowledge Proof contract (ZSC)

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
shielded_contract_id
required
string^0x[0-9a-f]{40}$
Request Body schema: application/json
from
required
Array of strings

Shielded account to transfer Zether tokens from

to
required
Array of strings

Shielded account to transfer Zether tokens to

amount
required
integer

The amount of Zether tokens to transfer

decoys
Array of Array of stringss

Optional. List of shielded accounts to add to the anonymity set to increase security of the transfer transaction

Responses

201

Transfer Successful

post /contracts/{shielded_contract_id}/transfer

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts/{shielded_contract_id}/transfer

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "from":
    [
    ],
  • "to":
    [
    ],
  • "amount": 0,
  • "decoys":
    [
    ]
}

Get shielded account balance

Returns Zether token balance for the shielded account corresponding to the given Ethereum account

Authorizations:
path Parameters
service_id
required
string^[0-9a-z]{10}$
shielded_contract_id
required
string^0x[0-9a-f]{40}$
ethAccount
required
string^0x[0-9a-f]{40}$

Responses

200

Balance Successfully Retrieved

get /contracts/{shielded_contract_id}/balanceOf/{ethAccount}

Each Kaleido service instance gets assigned a unique hostname. The service URL can be obtained from the /status endpoint for that service. E.g: https://console.kaleido.io/api/v1/c/{consortia_id}/e/{environment_id}/services/{service_id}/status

https://service_host/api/v1/contracts/{shielded_contract_id}/balanceOf/{ethAccount}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result": 0
}