Skip to main content

contracts_send_proposal

Creates an escrow contract proposal and sends it to the counterparty, locking this wallet's share of the escrowed coins until the proposal is accepted or expires.

The wallet building the proposal is side "A" (normally the buyer); the counterparty is side "B" (normally the seller). The proposal carries a two-of-two multisig escrow template funded with to_pay plus both pledges, so accepting it requires side B to contribute its own pledge and the release fee.

Request​

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "contracts_send_proposal",
  "params": {
    "details": {
      "t": "Laptop purchase, order #4471",
      "c": "Ship to the address given in the order, tracking number required",
      "a_addr": "NiRqzHVJfBJUj1WBUvHTPzYAJ4cKA6PQb2ZR33ZmS4Zp7DDcUxUE29nAkMtLPfCPXwPUgvYRZZ9NM2gN4uRRP1e12wTGSCMzn",
      "b_addr": "NiRs1YkQ8jTPzVCkR4h8nDdWq7BvXZ2LmA6ecNu3TgKoP9RfHy5UwJ4bMxLc7DnQaEuVt2SgYkRp8NwFz3XmB6dK14vHTQjRa",
      "to_pay": 1200000000000,
      "a_pledge": 600000000000,
      "b_pledge": 600000000000
    },
    "payment_id": "60900e5603bf96e3",
    "expiration_period": 86400,
    "fee": 10000000000,
    "b_fee": 10000000000,
    "fake_outputs_count": 10,
    "unlock_time": 0
  }
}

Request parameters​

  • details - object; the private terms of the contract. It is encrypted for the counterparty and embedded into the escrow template transaction. Field names are the compact keys used on the wire.
  • details.t - string; contract title or short description of the subject of the deal.
  • details.c - string; free-form comment with additional information such as an order ID or delivery details.
  • details.a_addr - string; address of side A, the party sending the proposal (normally the buyer). Must be an address of this wallet.
  • details.b_addr - string; address of side B, the counterparty that will receive and accept the proposal (normally the seller).
  • details.to_pay - unsigned int; the payment for the goods or service, in atomic units (1 coin = 10^12 atomic units). Provided by side A and released to side B on normal completion.
  • details.a_pledge - unsigned int; collateral deposited by side A, in atomic units. Returned to side A on normal completion or cancellation, burned on termination.
  • details.b_pledge - unsigned int; collateral required from side B, in atomic units. Side B contributes it when accepting the proposal.
  • payment_id - string; optional payment ID attached to the escrow template transaction, typically supplied by the seller to identify the order. Pass an empty string when not needed.
  • expiration_period - unsigned int; number of seconds, counted from the moment the proposal is sent, during which side B may accept it. The proposal's expiration timestamp is the current core time plus this value; once it passes, the coins reserved by side A are released back.
  • fee - unsigned int; fee for the proposal transaction itself, paid by side A, in atomic units.
  • b_fee - unsigned int; fee reserved inside the escrow template to cover the future release transaction, in atomic units. It is added on top of to_pay and both pledges in the multisig output and is contributed by side B when it accepts.
  • fake_outputs_count - unsigned int; number of decoy outputs mixed into the inputs of the escrow template transaction (the ring size minus one).
  • unlock_time - unsigned int; lock applied to the escrow template outputs. If nonzero and greater than or equal to 500000000, it is a unix timestamp; smaller nonzero values are treated as a minimum block height. Use 0 for no additional lock.

Response​

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "status": "OK"
  }
}

Response information​

  • status - string; result of sending the proposal. OK means the proposal transaction was built and broadcast. Other possible values are UNCONFIRMED, BAD, SPENT, BAD_ADDRESS and INTERNAL_ERROR.

The contract identifier is not returned by this call. After the proposal transaction is processed, the new contract appears in contracts_get_all in state 1 (proposal sent) with its contract_id — the multisig output id — which is the handle used by all other contract methods.