PolySwarmPolySwarmPolySwarmPolySwarm
Go to PolySwarm
Home

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.
URL /<ipfshash>
Method GET
URL /<ipfshash>/<int:id_>
Method GET
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.

  1. Upon receiving transaction data from a transaction dependent endpoint
  2. Sign the Transaction data with your private key
  3. 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"
  }
}

Articles in This Section

(Legacy) Windows + VirtualBox

If your computer is running Windows Server 2016 or Windows 10 Pro (version 1809+), we recommend you conduct Engine development inside of a Windows Container...

Integration Testing

The PolySwarm marketplace is composed of a myriad of participants and technologies...

Roles in the Marketplace

PolySwarm is a threat intelligence marketplace with Engines supplying intelligence, Ambassadors brokering access to the intelligence and Arbiters determining ground truth, mediating the marketplace...

Help

2020 © PolySwarm Pte. Ltd.