ODE-Draft.md

OpenAPI Decentralisation Extensions (DRAFT)

This specification builds upon OpenAPI Version 2.0

Swagger Object Extensions

The following fields MAY be added to the Swagger Object:

Field Name	Type	Description
x-contracts	[Contract Object]	refers to a list of ContractInfo objects

Operation Object Extensions

The Operation Object MAY include the following fields:

Field Name	Type	Description
x-contract	Payment Object	Describes which contract is required to interact with this endpoint

Standard Payment Interfaces

Subscription

The subscription identity is the Ethereum address of the subscriber.

On chain interaction

MUST define the following methods in its ABI:

Method	Description
register	MAY require a value transfer. If successful, subsequent evaluations of isRegistered with the transaction source address MUST return true.
unregister	If successful, subsequent evaluations of isRegistered with the transaction source address MUST return false.
isRegistered	Constant. Returns true if the address is registered, false otherwise.

Additional addressing and identification methods may be added to this specification later.

Off chain interaction

If HTTP requests are used as transport, the following request header has to be included in order to use the operation:

Field name	Description	Example
X-Signature	The hash of the own address concatenated with the SHA3-256 hash of the request, signed with the private key in hexadecimal notation	X-Signature: 46f0c7b8dff95f82437ea[...]

It may be retrieved using

web3.eth.sign(accounts[0], accounts[0])

Micropayment

On chain interaction

MUST define the following methods in its ABI:

Method	Description
verify	Constant. Verifies a signed statement adjusting the payment channel balance. Returns true if the statement is valid, false otherwise.
claim	Allows the receiver to claim all funds assigned to him, transferring it to his address.
deposit	Allows the sender to increase the value of the channel.
reclaim	After the specified delay, the sender can reclaim his funds.

Off chain interaction

If HTTP requests are used as transport, the following request header has to be included in order to use the operation:

Field name	Description	Example
X-Signature	A signed statement adjusting the payment channel balance in hexadecimal notation. MUST return true when evaluated with the contracts verify function.	X-Signature: 46f0c7b8dff95f8243...

Objects

Contract Object

Field Name	Type	Description
name	string	Required. MUST match the name of the contract in the source code on this address.
type	string	Required. MUST be the name of one of the Standard Payment Interfaces.
address	string	Required. The contract address is given in the hexadecimal representation, without a preceding 0x. The address MAY use the default checksum pattern.
info	Contract Info Object	Required. MUST refer to the contract info object that was created by the compiler.

Contract Info Object

After compiling a contract, it can be retrieved by Web3 using

contract.test.info

Example (as of 15.03.2016):

{
  abiDefinition: [],
  compilerOptions: "--bin --abi --userdoc --devdoc --add-std --optimize -o /tmp/solc109037226",
  compilerVersion: "0.3.0",
  developerDoc: {
    methods: {}
  },
  language: "Solidity",
  languageVersion: "0.3.0",
  source: "contract test {}",
  userDoc: {
    methods: {}
  }
}

Payment Object

Field Name	Type	Description
name	string	The name of the Contract Object this payment path uses.
value	integer	The cost of this request in Wei. May only be used if the Contract Object is of type "Micropayment".