NAV Navbar
curl

Introduction

This page describes the walrus HTTP API. walrus is an unprivileged wallet server that tracks transactions and spendable outputs associated with a set of addresses. Like the rest of the us project, walrus presents a low-level interface and is targeted towards developers, not end-users. The goal is to provide a flexible, performant API that is suitable for exchanges, web wallets, and other applications that require precise control of their siacoins.

Authentication

The walrus API is currently unauthenticated.

Routes

Add an Address

Example Request:

curl "localhost:9380/addresses" \
  -X POST \
  -d '{
    "unlockConditions": {
        "publicKeys": [ "ed25519:fa48a995dc17f978916d334afb0a28d04215a40fddc33db10d8a17b2ca93f6d4" ],
        "signaturesRequired": 1
    },
    "keyIndex": 1
  }'

Example Response:

"8066f825fd680559acba2c14ca7e8b0f4aa5e8a1eece3908485953d6a2e8ce3b991322eaf7d1"

Adds a set of unlock conditions to the wallet, returning the corresponding address. Future transactions and outputs relevant to this address will be recorded.

HTTP Request

POST http://localhost:9380/addresses

Errors

Code Description
400 Invalid unlock conditions or key index

Remove an Address

Example Request:

curl "localhost:9380/addresses/8066f825fd680559acba2c14ca7e8b0f4aa5e8a1eece3908485953d6a2e8ce3b991322eaf7d1" \
  -X DELETE

Removes an address from the wallet. Future transactions and outputs relevant to this address will not be recorded.

HTTP Request

DELETE http://localhost:9380/addresses/<addr>

URL Parameters

Parameter Description
addr The address to remove

Errors

Code Description
400 Invalid address

List Addresses

Example Request:

curl "localhost:9380/addresses"

Example Response:

[
  "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
  "5ac6af95fe284b4bbb0110ef51d3c90f3e9ea37586352ec83bad569230bad7f37a452c0a2a2f"
]

Lists all addresses known to the wallet.

HTTP Request

GET http://localhost:9380/addresses

Errors

None

Get Address Info

Example Request:

curl "localhost:9380/addresses/5ac6af95fe284b4bbb0110ef51d3c90f3e9ea37586352ec83bad569230bad7f37a452c0a2a2f"

Example Response:

{
  "unlockConditions": {
    "publicKeys": [
      "ed25519:0ea4e46899fe246e14122e3ca5865a7006d99086c52b1c63ab0e32226e56a7a1"
    ],
    "signaturesRequired": 1
  },
  "keyIndex": 1
}

Returns information about a specific address, including its unlock conditions and the index it was derived from.

HTTP Request

GET http://localhost:9380/addresses/<addr>

URL Parameters

Parameter Description
addr The address to query

Errors

Code Description
400 Address is invalid
404 Address does not belong to the wallet

Get the Current Balance

Example Request:

curl "localhost:9380/balance?limbo=true"

Example Response:

"123000000000000000000000000000"

Returns the current wallet balance in hastings. This is equivalent to summing the values of the outputs returned by /utxos. If the limbo flag is set, the balance incorporates any transactions currently in Limbo.

HTTP Request

GET http://localhost:9380/balance

URL Parameters

Parameter Description
limbo If true, incorporate Limbo transactions

Errors

None

List Block Rewards

Example Request:

curl "localhost:9380/blockrewards?max=1"

Example Response:

[
  {
    "id": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
    "value": "123000000000000000000000000000",
    "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
    "timelock": 123456
  }
]

Lists the block rewards tracked by the wallet. A block reward is the sum of the block subsidy (the new siacoins minted in the block) and the fees within the block's transactions. Technically, Sia allows this reward to be split among an arbitrary number of parties, but in practice the reward is paid out to a single address.

HTTP Request

GET http://localhost:9380/blockrewards

Query Parameters

Parameter Description
max The maximum number of block rewards to return

Errors

None

Broadcast a Transaction Set

Example Request:

curl "localhost:9380/broadcast" \
  -X POST \
  -d '[{
    "siacoinInputs": [{
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "unlockConditions": {
        "publicKeys": [ "ed25519:8408ad8d5e7f605995bdf9ab13e5c0d84fbe1fc610c141e0578c7d26d5cfee75" ],
        "signaturesRequired": 1
      }
    }],
    "siacoinOutputs": [{
      "value": "100000000000000000000000000000",
      "unlockHash": "df1b42c80b5f7a67331893fde0923a5071d6d7dff4c78baec547cf5ca4d314a1d78b6b1c8d42"
    }],
    "minerFees": [ "13000000000000000000000000000" ],
    "transactionSignatures": [{
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "rFtBFv9oeScpO3mhp6O2liMwBKYXn05SaOmzhhjQtIkOwAClaJTpLEKn3U26zYis2AG2tH2idWSJNZXNSVa8DQ=="
    }]
  }]'

Broadcasts the supplied transaction set to all connected peers.

HTTP Request

POST http://localhost:9380/broadcast

Errors

Code Description
400 Transaction set is invalid

Get Consensus Info

Example Request:

curl "localhost:9380/consensus"

Example Response:

{
  "height": 1368,
  "ccid": "ffdb020d509773476617e5805923f81025bbf7b77d4a1691489cfc574b0b3b61"
}

Returns the current blockchain height and consensus change ID. The latter is a unique ID that changes whenever blocks are added to the blockchain.

HTTP Request

GET http://localhost:9380/consensus

Errors

None

Example Request:

curl "localhost:9380/fee"

Example Response:

"123000000000"

Returns the current recommended transaction fee in hastings per byte of the Sia-encoded transaction.

HTTP Request

GET http://localhost:9380/consensus

Errors

None

List File Contracts

Example Request:

curl "localhost:9380/filecontracts?max=1"

Example Response:

[
  {
    "id": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
    "filesize": 16777216,
    "fileMerkleRoot": "966ae3a6b1b86bcf35bfa2a1482a2d3e78cb59e47161442b7aa50646d0fb39c9",
    "windowStart": 123000,
    "windowEnd": 123456,
    "payout": "123000000000000000000000000000",
    "validProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12145600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "278900000000"
      },
    ],
    "missedProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12145600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "278900000000"
      },
      {
        "unlockHash": "000000000000000000000000000000000000000000000000000000000000000089eb0d6a8a69",
        "value": "3141592653"
      },
    ],
    "unlockHash": "52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c64981855ad8681d",
    "unlockConditions": {
      "publicKeys": [
        "ed25519:c00913e02a63e4cf532d9b2ce282fad85af699815c18c595ea804462a794f751",
        "ed25519:120e5183722b7e809298a7cba681b0d32e04e460641046199a371301300174b1",
      ],
      "signaturesRequired": 2
    },
    "revisionNumber": 1
  },
]

Lists the file contracts relevant to the wallet. Each element represents the most recent on-chain revision of a given contract.

HTTP Request

GET http://localhost:9380/filecontracts

Query Parameters

Parameter Description
max The maximum number of contracts to return

Errors

None

List File Contract History

Example Request:

curl "localhost:9380/filecontracts/b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8"

Example Response:

[
  {
    "id": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
    "filesize": 16777216,
    "fileMerkleRoot": "966ae3a6b1b86bcf35bfa2a1482a2d3e78cb59e47161442b7aa50646d0fb39c9",
    "windowStart": 123000,
    "windowEnd": 123456,
    "payout": "123000000000000000000000000000",
    "validProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12145600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "278900000000"
      },
    ],
    "missedProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12145600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "278900000000"
      },
      {
        "unlockHash": "000000000000000000000000000000000000000000000000000000000000000089eb0d6a8a69",
        "value": "3141592653"
      },
    ],
    "unlockHash": "52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c64981855ad8681d",
    "unlockConditions": {
      "publicKeys": [
        "ed25519:c00913e02a63e4cf532d9b2ce282fad85af699815c18c595ea804462a794f751",
        "ed25519:120e5183722b7e809298a7cba681b0d32e04e460641046199a371301300174b1",
      ],
      "signaturesRequired": 2
    },
    "revisionNumber": 1
  },
  {
    "id": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
    "filesize": 4194304,
    "fileMerkleRoot": "0194fdc2fa2ffcc041d3ff12045b73c86e4ff95ff662a5eee82abdf44a2d0b75",
    "windowStart": 123000,
    "windowEnd": 123456,
    "payout": "123000000000000000000000000000",
    "validProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12345600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "78900000000"
      },
    ],
    "missedProofOutputs": [
      {
        "unlockHash": "2f8282cbe2f9696f3144c0aa4ced56dbd967dc2897806af3bed8a63aca16e18b686ba0dc208c",
        "value": "12345600000000"
      },
      {
        "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f",
        "value": "78900000000"
      },
      {
        "unlockHash": "000000000000000000000000000000000000000000000000000000000000000089eb0d6a8a69",
        "value": "3141592653"
      },
    ],
    "unlockHash": "52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c64981855ad8681d",
    "revisionNumber": 0
  }
]

Lists the history of on-chain revisions made to a given file contract, ordered newest-to-oldest. The initial file contract is the last element of the array.

HTTP Request

GET http://localhost:9380/filecontracts

Errors

None

List Limbo Transactions

Example Request:

curl "localhost:9380/limbo"

Example Response:

[
  {
    "siacoinInputs": [{
      "parentID": "b87491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "unlockConditions": {
        "publicKeys": [ "ed25519:37e32b4a07d5a617c8b872daabcba320d604f3c5017c580956c1ac42c37f8059" ],
        "signaturesRequired": 1
      }
    }],
    "siacoinOutputs": [{
      "value": "123000000000000000000000000000",
      "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f"
    }],
    "minerFees": [ "22500000000000000000000" ],
    "transactionSignatures": [{
      "parentID": "b87491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "WbJO3jeLBgzbMZI7D4yx5dNrX5Qw2e3/8lTakL/F23e3DL0nG2O02zUmdlq9466lx9uhfT3ejJOsO1oB3lMZBQ=="
    }],
    "limboSince": "1993-04-12T23:25:11-05:00"
  },
]

Lists transactions that are in Limbo.

HTTP Request

GET http://localhost:9380/limbo

Errors

None

Add a Transaction to Limbo

Example Request:

curl "localhost:9380/limbo/8d16e3de006a57028fd014ab85c2a76a32c5bbd2e1df9340b04795734c9c3372" \
  -X PUT \
  -d '{
    "siacoinInputs": [{
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "unlockConditions": {
        "publicKeys": [ "ed25519:8408ad8d5e7f605995bdf9ab13e5c0d84fbe1fc610c141e0578c7d26d5cfee75" ],
        "signaturesRequired": 1
      }
    }],
    "siacoinOutputs": [{
      "value": "100000000000000000000000000000",
      "unlockHash": "df1b42c80b5f7a67331893fde0923a5071d6d7dff4c78baec547cf5ca4d314a1d78b6b1c8d42"
    }],
    "minerFees": [ "13000000000000000000000000000" ],
    "transactionSignatures": [{
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "rFtBFv9oeScpO3mhp6O2liMwBKYXn05SaOmzhhjQtIkOwAClaJTpLEKn3U26zYis2AG2tH2idWSJNZXNSVa8DQ=="
    }]
  }'

Places a transaction in Limbo.

HTTP Request

PUT http://localhost:9380/limbo/<txid>

URL Parameters

Parameter Description
txid The ID of the transaction to add

Errors

Code Description
400 ID is invalid

Remove a Transaction from Limbo

Example Request:

curl "localhost:9380/limbo/8d16e3de006a57028fd014ab85c2a76a32c5bbd2e1df9340b04795734c9c3372" \
  -X DELETE

Removes a transaction from Limbo.

HTTP Request

DELETE http://localhost:9380/limbo/<txid>

URL Parameters

Parameter Description
txid The ID of the transaction to remove

Errors

Code Description
400 ID is invalid

Add a Transaction Memo

Example Request:

curl "localhost:9380/memos/2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba" \
  -X PUT
  -d 'My example memo'

Adds a memo for a transaction, overwriting the previous memo if it exists.

HTTP Request

PUT http://localhost:9380/memos/<txid>

URL Parameters

Parameter Description
txid The ID of the transaction

Errors

Code Description
400 Transaction ID is invalid

Get a Transaction Memo

Example Request:

curl "localhost:9380/memos/2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba"

Response body:

My example memo

Retrieves the memo for a transaction.

HTTP Request

GET http://localhost:9380/memos/<txid>

URL Parameters

Parameter Description
txid The ID of the transaction

Errors

Code Description
400 Transaction ID is invalid

List Transactions

Example Request:

curl "localhost:9380/transactions"

Example Response:

[
  "2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba",
  "355e6839329ff8cbc658d0b661a938c1988d0addce6b935b0d56c074cc3532bf",
  "3d9d51c636a736587b77a9e88d901d12acd0d49fbf92d27c8f8379f1510596bf",
  "e77cae8edef455685f792483b864b6489dec74284b91a380cb3221365c239ca9",
  "7e3f8ccc2d8b559fca057ebe5be4dfae99b7c9fcd4693c3c1b8e70894536c52a"
]

To retrieve just the three most recent transactions:

curl "localhost:9380/transactions?max=3"

Example Response:

[
  "2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba",
  "355e6839329ff8cbc658d0b661a938c1988d0addce6b935b0d56c074cc3532bf",
  "3d9d51c636a736587b77a9e88d901d12acd0d49fbf92d27c8f8379f1510596bf",
]

To limit the results to transactions relevant to a given address:

curl "localhost:9380/transactions?addr=e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f"

Example Response:

[
  "2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba",
  "3d9d51c636a736587b77a9e88d901d12acd0d49fbf92d27c8f8379f1510596bf",
  "e77cae8edef455685f792483b864b6489dec74284b91a380cb3221365c239ca9",
  "7e3f8ccc2d8b559fca057ebe5be4dfae99b7c9fcd4693c3c1b8e70894536c52a"
]

Lists the IDs of transactions relevant to the wallet. The IDs are ordered newest-to-oldest.

HTTP Request

GET http://localhost:9380/transactions?addr=<addr>&max=<max>

Query Parameters

Parameter Description
addr Return only transactions relevant to this address
max The maximum number of transactions to return

Errors

Code Description
400 Invalid address or maximum

Get Transaction Info

Example Request:

curl "localhost:9380/transactions/2936d6eab2272dda76603aa8078be02d979cf52ac3d06c799536c725e32686ba"

Example Response:

{
  "transaction": {
    "siacoinInputs": [{
      "parentID": "b87491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "unlockConditions": {
        "publicKeys": [ "ed25519:37e32b4a07d5a617c8b872daabcba320d604f3c5017c580956c1ac42c37f8059" ],
        "signaturesRequired": 1
      }
    }],
    "siacoinOutputs": [{
      "value": "123000000000000000000000000000",
      "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f"
    }],
    "minerFees": [ "22500000000000000000000" ],
    "transactionSignatures": [{
      "parentID": "b87491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "WbJO3jeLBgzbMZI7D4yx5dNrX5Qw2e3/8lTakL/F23e3DL0nG2O02zUmdlq9466lx9uhfT3ejJOsO1oB3lMZBQ=="
    }]
  },
  "blockID": "00000000000000002ac0219169abcdfece33725d0a79e77735be27b0932d8be3",
  "blockHeight": "123456",
  "timestamp": "2019-08-01T13:17:04.641427-04:00",
  "feePerByte": "48491379310344827586",
  "inflow": "123000000000000000000000000000",
  "outflow": "22500000000000000000000"
}

Returns the transaction with the specified ID, along with various useful metadata. The transaction must appear in /transactions.

HTTP Request

GET http://localhost:9380/transactions/<txid>

URL Parameters

Parameter Description
txid The ID of the transaction to retrieve

Errors

Code Description
400 Invalid transaction ID
404 Unknown transaction

List Unspent Outputs

Example Request:

curl "localhost:9380/utxos?limbo=true"

Example Response:

[
  {
    "id": "8d16e3de006a57028fd014ab85c2a76a32c5bbd2e1df9340b04795734c9c3372",
    "value": "10000000000000000000000000000",
    "unlockHash": "5ac6af95fe284b4bbb0110ef51d3c90f3e9ea37586352ec83bad569230bad7f37a452c0a2a2f"
  },
  {
    "id": "d8412f884e85519a6896cac505b4eceafd16ed79ca5d2d44e0b24a80a9df8083",
    "value": "123000000000000000000000000000",
    "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f"
  }
]

Returns the outputs that the wallet can spend. If the limbo flag is set, the returned set incorporates any transactions currently in Limbo.

HTTP Request

GET http://localhost:9380/utxos

URL Parameters

Parameter Description
limbo If true, incorporate Limbo transactions

Errors

None

Get Unconfirmed Parents

Example Request:

curl "localhost:9380/unconfirmedparents" \
  -X POST \
  -d '{
    "transaction": {
      "siacoinInputs": [{
        "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
        "unlockConditions": {
          "publicKeys": [ "ed25519:8408ad8d5e7f605995bdf9ab13e5c0d84fbe1fc610c141e0578c7d26d5cfee75" ],
          "signaturesRequired": 1
        }
      }],
      "siacoinOutputs": [{
        "value": "100000000000000000000000000000",
        "unlockHash": "df1b42c80b5f7a67331893fde0923a5071d6d7dff4c78baec547cf5ca4d314a1d78b6b1c8d42"
      }],
      "minerFees": [ "13000000000000000000000000000" ]
    }
  }'

Example Response:

[
  {
    "siacoinInputs": [{
      "parentID": "487491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "unlockConditions": {
        "publicKeys": [ "ed25519:37e32b4a07d5a617c8b872daabcba320d604f3c5017c580956c1ac42c37f8059" ],
        "signaturesRequired": 1
      }
    }],
    "siacoinOutputs": [{
      "value": "123000000000000000000000000000",
      "unlockHash": "e506d7f1c03f40554a6b15da48684b96a3661be1b5c5380cd46d8a9efee8b6ffb12d771abe9f"
    }],
    "minerFees": [ "22500000000000000000000" ],
    "transactionSignatures": [{
      "parentID": "b87491287c34880a1b512f47ec932d777c6809672236e2533fd565969e69a09b",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "WbJO3jeLBgzbMZI7D4yx5dNrX5Qw2e3/8lTakL/F23e3DL0nG2O02zUmdlq9466lx9uhfT3ejJOsO1oB3lMZBQ=="
    }],
    "limboSince": "1993-04-12T23:25:11-05:00"
  },
]

Returns the unconfirmed parents of the transaction, i.e. the transactions currently in Limbo that created one or more outputs spent by the supplied transaction. These transactions must be included when the transaction is broadcast.

HTTP Request

POST http://localhost:9380/unconfirmedparents

Errors

None

Get the Current Seed Index

Example Request:

curl "localhost:9380/seedindex"

Example Response:

3

Returns the seed index that should be used to derive the next address.

HTTP Request

GET http://localhost:9380/seedindex

Errors

None

Limbo

There is a period of uncertainty between the transaction being broadcast to miners and the transaction actually appearing in the blockchain. If the transaction has insufficient fees, or is invalidated by a later block, miners may discard it. During this period of uncertainty, we say that the transaction's outputs are "in Limbo."

Limbo is important because, in order to make multiple transactions in quick succession, a wallet may need to spend outputs created in Limbo transactions. Although this "daisy-chaining" can be risky (since, if a Limbo transaction does not make it into a block, all of its "children" become invalid as well), it is necessary to avoid excessive wait times between transactions.

After a transaction has been in Limbo for a sufficiently long time, it is typically safe to assume that it will never be included in a future block. The transaction may then be manually removed from Limbo, allowing its outputs to be reused in a different transaction without risking a double-spend.

Transaction Structure

{
  "siacoinInputs": [
    {
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "unlockConditions": {
        "publicKeys": [ "ed25519:8408ad8d5e7f605995bdf9ab13e5c0d84fbe1fc610c141e0578c7d26d5cfee75" ],
        "signaturesRequired": 1
      }
    }
  ],
  "siacoinOutputs": [
    {
      "value": "10000000000000000000000000000",
      "unlockHash": "5ac6af95fe284b4bbb0110ef51d3c90f3e9ea37586352ec83bad569230bad7f37a452c0a2a2f"
    },
    {
      "value": "100000000000000000000000000000",
      "unlockHash": "df1b42c80b5f7a67331893fde0923a5071d6d7dff4c78baec547cf5ca4d314a1d78b6b1c8d42"
    }
  ],
  "minerFees": [ "13000000000000000000000000000" ],
  "transactionSignatures": [
    {
      "parentID": "b8c63a8f435bfff7bf8c1f6c7ece0066599fa4e08cb74ab5929e84b014e408c8",
      "publicKeyIndex": 0,
      "coveredFields": { "wholeTransaction": true },
      "signature": "rFtBFv9oeScpO3mhp6O2liMwBKYXn05SaOmzhhjQtIkOwAClaJTpLEKn3U26zYis2AG2tH2idWSJNZXNSVa8DQ=="
    }
  ]
}

A typical transaction can be seen to the right. A brief overview of each field follows.

First are the siacoinInputs. Each input spends an output created by a previous transaction. The parentID identifies which output is being spent, and the unlockConditions reveal the preimage of the unlock hash (also known as an address). Unlock conditions consist of a set of publicKeys, a number of signaturesRequired, and a timelock. The vast majority of unlock conditions use a single public key and no timelock (i.e. a timelock of 0); these are known as "standard unlock conditions."

Next come the siacoinOutputs. Each output specifies an unlockHash (address) and a value of coins to send to that address. When these outputs are later spent, the unlockConditions revealed in the input must hash to the unlockHash specified in the output.

Next are the minerFees. Unlike Bitcoin, the fees are specified explicitly: the sum of the inputs must equal the sum of the outputs plus the miner fees.

Finally come the transactionSignatures. Every input must have a corresponding signature. The parentID specifies which input is being signed, and the publicKeyIndex identifies which of the publicKeys in the input is being used to sign. The coveredFields indicate what transaction data is being signed; except for certain special cases (such as file contract revisions), it should always specify that the wholeTransaction is being signed. And of course, every transaction signature must include the actual cryptographic signature.