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 engine 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"
}
}