polyswarmd API

polyswarmd is a convenience daemon that provides a simple REST API for interacting with the PolySwarm marketplace. Specifically, polyswarmd handles interaction with Ethereum and IPFS nodes on clients' behalf.

Bounties API

Bounty Parameters


URL	`/bounties/parameters?chain=[chain_name]`
Method	`GET`

Post Bounty

Called by end users and ambassadors to post a bounty.


URL	`/bounties?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


amount	The amount of NCT to post as a reward.
uri	URI of the artifacts comprising this bounty.
duration	Duration of this bounty in blocks.

{
  "amount": "[string minimum length 1 / max length 100]",
  "uri": "[string minimum length 1 / max length 100]",
  "duration": "[integer minimum 1]"
}

Data example - All fields must be sent.

{
  "amount": "30000",
  "uri": "QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6",
  "duration": 10
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    },
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Vote on Bounty

Called by arbiter after bounty expiration with a malicious or benign vote for each artifact, contributing to the final ground truth determination.


URL	`/bounties/<uuid:guid>/vote?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


votes	Array of votes representing ground truth for the bounty's artifacts.
valid_bloom	If this is a bloom vote.

{
  "votes": "[array with a max of 256 boolean items]",
  "valid_bloom": "[boolean]"
}

Data example - All fields must be sent.

{
  "votes": "[true, false, true, true, false]",
  "valid_bloom": "true"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Settle Bounty

Callable after the voting window has closed to handle reward disbursal.


URL	`/bounties/<uuid:guid>/settle?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

No data needed for this request

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Assert on bounty

Called by security experts to post an assertion on a bounty.


URL	`/bounties/<uuid:guid>/assertions?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


bid	The amount of NCT to stake.
mask	The artifacts to assert on from the set in the bounty.

And one of the following:


verdicts	Array of verdicts on bounty artifacts.
commitment	*A commitment hash equal to `keccak256(verdicts ^ keccak256(nonce) ^ sender))`

*where:

- verdicts is the array of verdicts represented as a big-endian bitset
- nonce is a 256-bit random non-zero integer
- sender is the address of the microengine placing the assertion

{
  "bid": "[string minimum length 1 with max length 100]",
  "mask": "[array with a max of 256 boolean items]",
  "verdicts": "[array with a max of 256 boolean items]"
}

Data example - All fields must be sent.

{
  "bid": "200000",
  "mask": "[true, true, true]",
  "verdicts": "[false, true, false]"
}

Success response


Condition	If everything is OK the generated nonce will be created later used for reveal (unless commitment hash was provided) and you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{ "nonce": 432984098,
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Reveal bounty assertions

Called by arbiter after bounty expiration to settle with their ground truth determination and pay out assertion rewards.


URL	`/bounties/<uuid:guid>/vote?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


nonce	The nonce used to generate the commitment hash (returned from asserting on a bounty).
verdicts	The verdicts making up this assertion.
metadata	To include in the assertion (can be empty string).

{
  "nonce": "[string minimum length 1 with max length 100]",
  "verdicts": "[array with a max of 256 boolean items]",
  "metadata": "[string minimum length 1 with max length 1024]"
}

Data example - All fields must be sent.

{
  "nonce": "123",
  "verdicts": "[true, false, true]",
  "metadata": "Dropper"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Get a bounty's info


URL	`/<uuid:guid>?chain=[chain_name]`
Method	`GET`

Get assertions for a bounty


URL	`/<uuid:guid>/assertions?chain=[chain_name]`
Method	`GET`

Get an assertion for a bounty


URL	`/<uuid:guid>/assertions/<int:id_>?chain=[chain_name]`
Method	`GET`

Get bloom for a bounty


URL	`/<uuid:guid>/bloom?chain=[chain_name]`
Method	`GET`

Get votes for a bounty


URL	`/<uuid:guid>/votes?chain=[chain_name]`
Method	`GET`

Get a vote for a bounty


URL	`/<uuid:guid>/votes/<int:id_>?chain=[chain_name]`
Method	`GET`

Staking API

Staking Parameters


URL	`/staking/parameters?chain=[chain_name]`
Method	`GET`

Post Deposit Stake

Called by arbiters to deposit stake Nectar.


URL	`/staking/deposit?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


amount	The amount of NCT to add to current stake.

{
  "amount": "[string minimum length 1 / max length 100]"
}

Data example - All fields must be sent.

{
  "amount": "30000000000"
}

Post Withdrawal Stake

Called by arbiters to withdraw available staked Nectar.


URL	`/staking/withdraw?account=[eth_address]&chain=[chain_name]&base_nonce=[integer]`
Method	`POST`

Data constraints


amount	The amount of NCT to withdraw from current stake.

{
  "amount": "[string minimum length 1 / max length 100]"
}

Data example All fields must be sent.

{
  "amount": "30000000000"
}

Get total stake balance


URL	`/balances/<address>/staking/total`
Method	`GET`

Get withdrawable stake balance


URL	`/balances/<address>/staking/withdrawable`
Method	`GET`

Artifacts API

Post Artifact

Post an artifact to IPFS


URL	`/artifacts`
Method	`POST`

Data constraints

List of files to upload. You can upload a max of 256.

Get file links associated with hash


URL	`/<ipfshash>`
Method	`GET`

Get a link associated with hash and link index


URL	`/<ipfshash>/<int:id_>`
Method	`GET`

Get stats on artifact link


URL	`/<ipfshash>/<int:id_>/stat`
Method	`GET`

Offers API

Stateless offer API coming soon.

Create an offer channel

Called by an ambassador to deploy a new multi signature offer.


URL	`/offers?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


ambassador	Address of ambassador using channel.
expert	Address of expert using channel.
settlementPeriodLength	How long the parties have to dispute the settlement offer channel.
websocketUri	URI of socket to send messages to ambassador.

{
  "ambassador": "[string minimum length 42]",
  "expert": "[string minimum length 42]",
  "settlementPeriodLength": "[integer minimum 60]",
  "websocketUri": "[string with minimum length 1 max 32]"
}

Data example - All fields must be sent.

{
  "amount": "0x34E583cf9C1789c3141538EeC77D9F0B8F7E89f2",
  "uri": "0xf0243D9b2E332D7072dD4B143a881B3f135F380c",
  "duration": 80,
  "websocketUri": "ws://localhost:9999/echo"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Open channel

Called by ambassador to open channel with expert.


URL	`offers/open/<uuid:guid>?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Initial offer state.
v	The recovery id from signature of state string.
r	Output of ECDSA signature of state string.
s	Output of ECDSA signature of state string.

{
  "state": "[string minimum length 32]",
  "v": "[integer minimum 0]",
  "r": "[string minimum length 64]",
  "s": "[string minimum length 64]"
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc",
  "v": "27",
  "r": "0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9",
  "s": "0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Join channel

Called by expert to join ambassador channel.


URL	`offers/open?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Initial offer state.
v	The recovery id from signature of state string.
r	Output of ECDSA signature of state string.
s	Output of ECDSA signature of state string.

{
  "state": "[string minimum length 32]",
  "v": "[integer minimum 0]",
  "r": "[string minimum length 64]",
  "s": "[string minimum length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "v": "27",
  "r": "0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9",
  "s": "0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Cancel channel

Called by ambassador to cancel if the contract hasn't been joined yet.


URL	`offers/cancel?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Close channel

Called by any party with a both signatures on a state with a closed state flag set to 1.


URL	`/close?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Offer state with closed flag.
v	Array of the recovery ids from signature of state string for both parties.
r	Array of outputs of ECDSA signature of state string for both parties.
s	Array of outputs of ECDSA signature of state string for both parties.

{
  "state": "[string minimum length 32]",
  "v": "[array of 2 integers]",
  "r": "[array of 2 strings with min length 64]",
  "s": "[array of 2 strings with min length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "v": "[27, 28]",
  "r": "['0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9', 0x59e21a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9]",
  "s": "['0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66', '0x138ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66']"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Close challenged channel with timeout

Called by any party with a both signatures on a state that is the final challenge state.


URL	`/offers/closeChallenged?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Offer state with closed flag.
v	Array of the recovery ids from signature of state string for both parties.
r	Array of outputs of ECDSA signature of state string for both parties.
s	Array of outputs of ECDSA signature of state string for both parties.

{
  "state": "[string minimum length 32]",
  "v": "[array of 2 integers]",
  "r": "[array of 2 strings with min length 64]",
  "s": "[array of 2 strings with min length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "v": "[27, 28]",
  "r": "['0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9', 0x59e21a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9]",
  "s": "['0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66', '0x138ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66']"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Settle channel

Called by ambassador or expert to start initialize a disputed settlement using an agreed upon state. It starts a timeout for a reply using settlementPeriodLength.


URL	`/offers/settle?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Offer state both parties signed.
v	Array of the recovery ids from signature of state string for both parties.
r	Array of outputs of ECDSA signature of state string for both parties.
s	Array of outputs of ECDSA signature of state string for both parties.

{
  "state": "[string minimum length 32]",
  "v": "[array of 2 integers]",
  "r": "[array of 2 strings with min length 64]",
  "s": "[array of 2 strings with min length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "v": "[27, 28]",
  "r": "['0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9', 0x59e21a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9]",
  "s": "['0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66', '0x138ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66']"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Challenge settle channel state

Called by ambassador or expert to challenge a disputed state. The new state is accepted if it is signed by both parties and has a higher sequence number.


URL	`/offers/challenge?account=[eth_address]&base_nonce=[integer]`
Method	`POST`

Data constraints


state	Offer state both parties signed.
v	Array of the recovery ids from signature of state string for both parties.
r	Array of outputs of ECDSA signature of state string for both parties.
s	Array of outputs of ECDSA signature of state string for both parties.

{
  "state": "[string minimum length 32]",
  "v": "[array of 2 integers]",
  "r": "[array of 2 strings with min length 64]",
  "s": "[array of 2 strings with min length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "v": "[27, 28]",
  "r": "['0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9', 0x59e21a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9]",
  "s": "['0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66', '0x138ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66']"
}

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

{
  "transactions": [
    { "chainId": 1337,
      "data": "0x095ea7b30000000000000000000000007d012af57b89fceded483f6716d2f0862b3af396000000000000000000000000000000000000000000000000098a7d9b8314c000",
      "gas": 5000000,
      "gasPrice": 100000000000,
      "nonce": 748,
      "to": "0xEfEaF137150FC048B1d828B764e44f7ed628Bd66",
      "value": 0
    }
  ]
}

Get offer channel info


URL	`/offers/<uuid:guid>`
Method	`GET`

Get offer channel settlement period


URL	`/offers/<uuid:guid>/settlementPeriod`
Method	`GET`

Get ambassador websocket uri


URL	`/offers/<uuid:guid>/websocket`
Method	`GET`

Get pending offers


URL	`/offers/pending`
Method	`GET`

Get opened offers


URL	`/offers/opened`
Method	`GET`

Get closed offers


URL	`/offers/closed`
Method	`GET`

Get my offers


URL	`/offers/myoffers?account=[eth_address]`
Method	`GET`

Transaction Signing


URL	`/transactions?chain=[chain_here]`
Method	`POST`

All signed transactions are POSTed here to start the transaction on the chain of choice.

To add transaction signing to your polyswarmd dependent project you need to to write/use something that follows the steps below.

Upon receiving transaction data from a transaction dependent endpoint
Sign the Transaction data with your private key
POST the signed transaction to /transactions

There is a python example embedded below, though you can use any other language.

import json
import requests
from web3.auto import w3 as web3

POLYSWARMD_ADDR = 'localhost:31337'
KEYFILE = 'keyfile'
PASSWORD = 'password'
ADDRESS, PRIV_KEY = unlock_key(KEYFILE, PASSWORD)

def unlock_key(keyfile, password):
    """Open an encrypted keystore file and decrypt it"""
    with open(keyfile, 'r') as f:
        priv_key = web3.eth.account.decrypt(f.read(), password)

    address = web3.eth.account.privateKeyToAccount(priv_key).address
    return (address, priv_key)

def post_transactions(transactions):
    """Post a set of (signed) transactions to Ethereum via polyswarmd, parsing the emitted events"""
    signed = []
    for tx in transactions:
        s = web3.eth.account.signTransaction(tx, PRIV_KEY)
        raw = bytes(s['rawTransaction']).hex()
        signed.append(raw)

    uri = 'http://{0}/transactions'.format(POLYSWARMD_ADDR)

    response = requests.post(uri, data=json.dumps({'transactions': signed})):
    return response.json()

Success response


Condition	If everything is OK you will get an array of raw unsigned transactions to be signed and sent through the `/transactions` endpoint.
Status	200

Content example

[
  {
    "is_error": false,
    "message": "0x3ba9b38a6014048897a47633727eec4999d7936ea0f1d8e7bd42a51a1164ffad"
  },
]

Transaction Events

A list of events or errors that resulted from the transaction with the given hash.


URL	`/transactions/?chain=[chain_here]`
Method	`GET`

Data constraints


transactions	A list transaction hashes to check.

{
  "transactions": "[array of transaction hashes]",
}

Data example - All fields must be sent.

{
  "transactions": ["0x3ba9b38a6014048897a47633727eec4999d7936ea0f1d8e7bd42a51a1164ffad"],
}

Success response


Condition	If all of the transactions completed without reverting. (If some failed, it will return 400).
Status	200

Content example

{
  "transfers": [
    {
    "value": 20000000000000000,
    "from": "0x000000000000000000000000000000000",
    "to": "0x000000000000000000000000000000000"
    }
  ],
  "bounties": [
    {
      "guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
      "author": "0x000000000000000000000000000000000",
      "amount": "1000",
      "uri": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
      "expiration": "1000"
    }
  ],
  "assertions": [
    {
      "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
      "author": "0x000000000000000000000000000000000",
      "index": 0,
      "bid": "1000",
      "mask": [true],
      "commitment": "1000"
    }
  ],
  "reveals": [
    {
      "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
      "author": "0x000000000000000000000000000000000",
      "index": 0,
      "nonce": "0",
      "verdicts": [true],
      "metadata": ""
    }
  ],
  "votes": [
    {
      "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
      "votes": [true],
      "voter": "0x000000000000000000000000000000000"
    }
  ],
  "settles": [
    {
      "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
      "settler": "0x000000000000000000000000000000000",
      "payout": 0
    }
  ],
  "withdrawals": [
    {
      "to": "0x000000000000000000000000000000000",
      "value": 0
    }
  ],
  "deposits": [
    {
      "from": "0x000000000000000000000000000000000",
      "value": 0
    }
  ],
  "errors": []
}

State

Creating State

The state byte string contains details the ambassador and expert sign off on.


URL	`/offers/state`
Method	`POST`

Data constraints


close_flag	1 or 0 for is this state is closeable.
nonce	The sequnce of the state.
ambassador	Ambassador address.
expert	Expert address.
msig_address	Multi-signature address.
ambassador_balance	Balance in nectar for ambassador.
nectar_balance	Balance in nectar for expert.
guid	A globally
offer_amount	The offer amount paid for assertion.
artifact_hash (optional)	Cryptographic hash of the artifact.
ipfs_hash (optional)	The IPFS URI of the artifact.
engagement_deadline (optional)	Engagement Deadline.
assertion_deadline (optional)	Assertion Deadline.
current_commitment (optional)	Current commitment.
verdicts (optional)	Bitmap of verdicts.
meta_data (optional)	Meta data about current offer.

Example POST data

{
  "close_flag": 0,
  "nonce": 0,
  "ambassador": "0x000000000000000000000000000000000",
  "ambassador_balance": 100,
  "expert_balance": 0,
  "expert":"0x000000000000000000000000000000000",
  "msig_address": "0x05027017bd3284c3f794474cc9f047e247bea04a"
}

Gets transformed to the below bytes string in the response

0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc

Signing State

The offers api requires signed states. Here's an example of signing to create the v, r, and s signature pieces in Javascript.

const EthereumTx = require('ethereumjs-tx');
const keythereum = require('keythereum');

const DATADIR = '/home/user/.ethereum/priv_testnet';
const ADDRESS = '34e583cf9c1789c3141538eec77d9f0b8f7e89f2';
const PASSWORD = 'password';

const enc_key = keythereum.importFromFile(ADDRESS, DATADIR);
const key = keythereum.recover(PASSWORD, enc_key);

const buff_key = etherutils.toBuffer(key);
const state = web3.toHex("0x00000000000000000000000000000000000000000000000000000000....");
let msg = '0x' + etherutils.keccak(etherutils.toBuffer(state)).toString('hex');
msg = '0x' + etherutils.hashPersonalMessage(etherutils.toBuffer(msg)).toString('hex');
const sig = etherutils.ecsign(etherutils.toBuffer(msg), buff_key);
let r = '0x' + sig.r.toString('hex')
let s = '0x' + sig.s.toString('hex')
let v = sig.v

State Messages

Ambassadors open a websocket with the url defined in the contract.


Local	`ws://localhost:31337/messages/<uuid:guid>`

Data constraints


type	Type of message (payment, request, assertion).
state	Offer state.
toSocketUri (optional)	To send to a different person (defaults to the ambassador).
v (optional)	Recovery ids from signature of state string for both parties.
r (optional)	ECDSA signature of state string.
s (optional)	ECDSA signature of state string.

{
  "fromSocketUri": "[string]",
  "state": "[string minimum length 32]",
  "v": "[array of 2 integers]",
  "r": "[array of 2 strings with min length 64]",
  "s": "[array of 2 strings with min length 64]",
}

Data example - All fields must be sent.

See state explanation

{
  "state": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000f17f52151ebef6c7334fad080c5704d77216b732000000000000000000000000c5fdf4076b8f3a5357c5e395ab970b5b54098fef000000000000000000000000fa21e79ca2dfb3ab15469796069622903919159c00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000219ebb52f4e92c4fa554e80316b95d4adefb3ed600000000000000000000000000000000000000000000000000000000000001bc000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006e6f6e650000000000000000000000000000000000000000000000000000004c6f636b79",
  "fromSocketUri": "payment"
}

Events

A websocket for contract events.


Local	`ws://localhost:31337/events/<chain>`

Event Types

`Block`

Sent when a new block is mined, reports the latest block number.

Content example

{
  "event": "block",
  "data": {
    "number": 1000
  }
}

`Bounty`

Sent when a new bounty is posted.

Content example

{
  "event": "bounty",
  "data": {
    "guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "author": "0x000000000000000000000000000000000",
    "amount": "1000",
    "uri": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
    "expiration": "1000"
  }
}

`Assertion`

Sent when a new assertion to a bounty is posted.

Content example

{
  "event": "assertion",
  "data": {
    "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "author": "0x000000000000000000000000000000000",
    "index": 0,
    "bid": "1000",
    "mask": [true],
    "commitment": "1000"
  }
}

`Reveal`

Sent when an assertion to a bounty is revealed.

Content example

{
  "event": "assertion",
  "data": {
    "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "author": "0x000000000000000000000000000000000",
    "index": 0,
    "nonce": "0",
    "verdicts": [true],
    "metadata": ""
  }
}

`Vote`

Sent when an arbiter votes on a bounty.

Content example

{
  "event": "vote",
  "data": {
    "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "votes": [true],
    "voter": "0x000000000000000000000000000000000"
  }
}

`Quorum`

Sent when arbiters have reached quorum on a bounty.

Content example

{
  "event": "quorum",
  "data": {
    "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "quorum_block": 1000
  }
}

`Settled`

Sent when a participant settles their portion of a bounty.

Content example

{
  "event": "settled_bounty",
  "data": {
    "bounty_guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "settler": "0x0000000000000000000000000000000000000000",
    "payout": 0
  }
}

`Initialized Channel`

Sent when a new channel is initialized.

Content example

{
  "event": "initialized_channel",
  "data": {
    "guid": "20085e89-c5e3-4fb4-a6cd-055feb342097",
    "ambassador": "0x0000000000000000000000000000000000000000",
    "expert": "0x0000000000000000000000000000000000000000",
    "mutl_signature": "0x0000000000000000000000000000000000000000"
  }
}