mirror of
https://github.com/hyperledger/fabric-samples.git
synced 2026-06-17 15:35:09 +00:00
519 lines
14 KiB
YAML
519 lines
14 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Tokens
|
|
version: "1.0"
|
|
description: |-
|
|
Issue, hold, transfer and redeem tokens. Backed by a distributed ledger,
|
|
preserving privacy using Zero Knowledge Proofs. This API definition fronts 4 different services, which each play a different
|
|
role in the ecosystem.
|
|
|
|
To try it out, let the Issuer issue some funds to one of the users. Watch the balances
|
|
get updated and see the transaction history. Transfer it to another account, or redeem
|
|
the tokens to destroy them.
|
|
servers:
|
|
- url: http://localhost:9000/api/v1/
|
|
description: auditor
|
|
- url: http://localhost:9100/api/v1/
|
|
description: issuer
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
|
|
paths:
|
|
# Auditor
|
|
/auditor/accounts/{id}:
|
|
servers:
|
|
- url: http://localhost:9000/api/v1/
|
|
description: auditor
|
|
get:
|
|
tags:
|
|
- auditor
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
- $ref: "#/components/parameters/code"
|
|
required: true
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/AccountSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
operationId: auditorAccount
|
|
summary: Get an account and their balance of a certain type
|
|
|
|
/auditor/accounts/{id}/transactions:
|
|
servers:
|
|
- url: http://localhost:9000/api/v1/
|
|
description: auditor
|
|
get:
|
|
tags:
|
|
- auditor
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
operationId: auditorTransactions
|
|
summary: Get all transactions for an account
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/TransactionsSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
|
|
# Issuer
|
|
/issuer/issue:
|
|
servers:
|
|
- url: http://localhost:9100/api/v1/
|
|
description: issuer
|
|
summary: Issue tokens to an account
|
|
post:
|
|
tags:
|
|
- issuer
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/IssueSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
requestBody:
|
|
description: Instructions to issue funds to an account
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TransferRequest"
|
|
operationId: issue
|
|
summary: Issue tokens of any kind to an account
|
|
|
|
# Owner
|
|
/owner/accounts:
|
|
servers:
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
get:
|
|
tags:
|
|
- owner
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/AccountsSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
operationId: ownerAccounts
|
|
summary: Get all accounts on this node and their balances of each type
|
|
|
|
/owner/accounts/{id}:
|
|
servers:
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
get:
|
|
tags:
|
|
- owner
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
- $ref: "#/components/parameters/code"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/AccountSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
operationId: ownerAccount
|
|
summary: Get an account and its balances of each token type
|
|
|
|
/owner/accounts/{id}/transactions:
|
|
servers:
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
get:
|
|
tags:
|
|
- owner
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
operationId: ownerTransactions
|
|
summary: Get all transactions for an account
|
|
description: |
|
|
Note that the system uses Unspent Transaction Outputs (UTXO).
|
|
For a transfer, you'll often see two transactions with the same id. The user specified amount goes
|
|
to the counterparty, and some other amount (the remaining part of the input token) goes back to the
|
|
sender!
|
|
|
|
This could be confusing for a user. A simple solution is to filter out the transactions with the same
|
|
sender and recipient.
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/TransactionsSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
|
|
/owner/accounts/{id}/transfer:
|
|
servers:
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
summary: Transfer tokens to another account
|
|
post:
|
|
tags:
|
|
- owner
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
name: id
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TransferRequest"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/TransferSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
operationId: transfer
|
|
summary: Transfer tokens to another account
|
|
|
|
/owner/accounts/{id}/redeem:
|
|
servers:
|
|
- url: http://localhost:9200/api/v1/
|
|
description: alice and bob
|
|
- url: http://localhost:9300/api/v1/
|
|
description: carlos and dan
|
|
summary: Redeem (burn) tokens
|
|
post:
|
|
tags:
|
|
- owner
|
|
parameters:
|
|
- $ref: "#/components/parameters/id"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RedeemRequest"
|
|
operationId: redeem
|
|
summary: Redeem (burn) tokens
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/RedeemSuccess"
|
|
default:
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
|
|
# Operations
|
|
/healthz:
|
|
get:
|
|
tags:
|
|
- operations
|
|
operationId: healthz
|
|
summary: Returns 200 if the service is healthy
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/HealthSuccess"
|
|
"503":
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
/readyz:
|
|
get:
|
|
tags:
|
|
- operations
|
|
operationId: readyz
|
|
summary: Returns 200 if the service is ready to accept calls
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/HealthSuccess"
|
|
"503":
|
|
$ref: "#/components/responses/ErrorResponse"
|
|
|
|
components:
|
|
responses:
|
|
AccountSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
payload:
|
|
$ref: "#/components/schemas/Account"
|
|
AccountsSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
payload:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Account"
|
|
TransactionsSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "transactions retrieved"
|
|
payload:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/TransactionRecord"
|
|
TransferSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
payload:
|
|
type: string
|
|
description: Transaction id
|
|
example:
|
|
message: transferred tokens
|
|
payload: 7c26ed6e5e05f7de81a82691b66b1069d1507d9edf3c7b78ea1fa98557ee57b4
|
|
RedeemSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: tokens redeemed
|
|
payload:
|
|
type: string
|
|
description: Transaction id
|
|
example: 7c26ed6e5e05f7de81a82691b66b1069d1507d9edf3c7b78ea1fa98557ee57b4
|
|
IssueSuccess:
|
|
description: Success or error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
- payload
|
|
properties:
|
|
message:
|
|
type: string
|
|
payload:
|
|
type: string
|
|
description: Transaction id
|
|
HealthSuccess:
|
|
description: Success response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: ok
|
|
example:
|
|
message: ok
|
|
|
|
ErrorResponse:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
schemas:
|
|
# Common
|
|
Amount:
|
|
description: The amount to issue, transfer or redeem.
|
|
type: object
|
|
required:
|
|
- code
|
|
- value
|
|
properties:
|
|
code:
|
|
description: the code of the token
|
|
default: EURX
|
|
type: string
|
|
value:
|
|
description: value in base units (usually cents)
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
example:
|
|
code: EURX
|
|
value: 100
|
|
Account:
|
|
type: object
|
|
description: Information about an account and its balance
|
|
required:
|
|
- id
|
|
- balance
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: account id as registered at the Certificate Authority
|
|
example: alice
|
|
balance:
|
|
type: array
|
|
description: balance in base units for each currency
|
|
items:
|
|
$ref: "#/components/schemas/Amount"
|
|
example:
|
|
id: alice
|
|
balance:
|
|
- code: EURX
|
|
value: 10000
|
|
- code: USDX
|
|
value: 200
|
|
Counterparty:
|
|
description: The counterparty in a Transfer or Issuance transaction.
|
|
required:
|
|
- node
|
|
- account
|
|
type: object
|
|
properties:
|
|
node:
|
|
description: The node that holds the recipient account
|
|
type: string
|
|
account:
|
|
type: string
|
|
example:
|
|
node: owner1
|
|
account: alice
|
|
TransactionRecord:
|
|
type: object
|
|
description: A transaction
|
|
required:
|
|
- id
|
|
- sender
|
|
- recipient
|
|
- amount
|
|
- timestamp
|
|
- status
|
|
- message
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: transaction id
|
|
sender:
|
|
type: string
|
|
description: the sender of the transaction
|
|
recipient:
|
|
type: string
|
|
description: the recipient of the transaction
|
|
amount:
|
|
$ref: "#/components/schemas/Amount"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: 'timestamp in the format: "2018-03-20T09:12:28Z"'
|
|
status:
|
|
type: string
|
|
description: Unknown | Pending | Confirmed | Deleted
|
|
message:
|
|
type: string
|
|
description: user provided message
|
|
example:
|
|
id: 123
|
|
sender: alice
|
|
recipient: bob
|
|
amount:
|
|
code: EURX
|
|
value: 100
|
|
timestamp: "2018-03-20T09:12:28Z"
|
|
status: Confirmed
|
|
message: ""
|
|
|
|
# Owner
|
|
TransferRequest:
|
|
description: Instructions to issue or transfer tokens to an account
|
|
required:
|
|
- counterparty
|
|
- amount
|
|
type: object
|
|
properties:
|
|
amount:
|
|
$ref: "#/components/schemas/Amount"
|
|
counterparty:
|
|
$ref: "#/components/schemas/Counterparty"
|
|
message:
|
|
description: optional message that will be sent and stored with the transfer transaction
|
|
type: string
|
|
RedeemRequest:
|
|
description: Instructions to redeem tokens from an account
|
|
required:
|
|
- amount
|
|
type: object
|
|
properties:
|
|
amount:
|
|
$ref: "#/components/schemas/Amount"
|
|
message:
|
|
description: optional message that will be visible to the auditor
|
|
type: string
|
|
Error:
|
|
required:
|
|
- message
|
|
- payload
|
|
type: object
|
|
properties:
|
|
message:
|
|
description: High level error message
|
|
type: string
|
|
payload:
|
|
description: Details about the error
|
|
type: string
|
|
example:
|
|
message: error message
|
|
payload: ""
|
|
parameters:
|
|
id:
|
|
name: id
|
|
schema:
|
|
example: alice
|
|
description: account id as registered at the Certificate Authority
|
|
type: string
|
|
in: path
|
|
required: true
|
|
code:
|
|
name: code
|
|
in: query
|
|
schema:
|
|
example: EURX
|
|
description: The token code to filter on
|
|
type: string
|
|
securitySchemes: {}
|
|
headers: {}
|
|
tags:
|
|
- name: issuer
|
|
description: can create tokens of any kind, and send them to owner accounts
|
|
- name: owner
|
|
description: is the service that hosts the keys and accounts of end users
|
|
- name: auditor
|
|
description: gets to see every transaction in the clear, and keeps a history
|
|
- name: operations
|
|
description: Service health and readiness
|
|
security: []
|