How to send transactions

Use the Orchestrate Gateway API to send transactions to an Ethereum Blockchain network. Orchestrate supports every type of Ethereum transaction:

Smart contract deployments: Registering a new smart contract on the Blockchain.
Smart contract transactions: Executing a function that changes the state of the Blockchain.
Transfer transactions: Send ETH to an account.
Raw transactions: Send transactions signed outside of Orchestrate (for example, from a hardware wallet).

All these type of transactions can be sent over a private Ethereum network (see Besu or GoQuorum for more information on private networks).

Tip

Check the REST API Reference or the JS SDK Reference for a detailed description of all endpoints.

Send a transaction

Prerequisites

A registered chain.
A registered account.
A registered smart contract (mandatory for contract deployments).

Send a transaction using the Orchestrate Gateway API by sending a POST request to the /transactions/send endpoint.

Tip

Every type of transaction have their own specific endpoint. See /transactions/deploy-contract, /transactions/transfer and /transactions/send-raw.

Example

REST Request

{
  "chain": "myChain",
  "labels": {
    "property1": "myLabel1",
    "property2": "myLabel2"
  },
  "params": {
    "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
    "methodSignature": "transfer(address,uint256)",
    "args": ["0x0eeae27a0cbfb02945720425d3b80c7e09728534", 500],
    "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",

  }
}

JavaScript (SDK)

const txResponse = await txClient.sendTransaction({
  chain: 'myChain',
  labels: {
    property1: 'myLabel1',
    property2: 'myLabel2'
  },
  params: {
    methodSignature: 'transfer(address,uint256)',
    args: ['0x0eeae27a0cbfb02945720425d3b80c7e09728534', 500],
    to: '0xfffae27a0cbfb02945720425d3b80c7e09728534',
    from: '0x1abae27a0cbfb02945720425d3b80c7e09728534',
  },
});

JSON response

{
  "uuid": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
  "chain": "myChain",
  "idempotencyKey": "myIdempotencyKey",
  "jobs": [
    {
      "uuid": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c"
      "chainUUID": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
      "labels": {
        "property1": "myLabel1",
        "property2": "myLabel2"
      },
      "logs": [...],
      "scheduleUUID": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
      "status": "STARTED",
      "tenantID": "foo",
      "transaction": {
        "data": "0xfe378324abcde723...",
        "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
        "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
        "updatedAt": "2020-07-09T12:35:42.115395Z",
        "createdAt": "2020-07-09T12:35:42.115395Z",
      },
      "type": "eth://ethereum/transaction",
      "createdAt": "2020-07-09T12:35:42.115395Z",
      "updatedAt": "2020-07-09T12:35:42.115395Z",
    }
  ],
  "params": {
    "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
    "methodSignature": "transfer(address,uint256)",
    "args": ["0x0eeae27a0cbfb02945720425d3b80c7e09728534", 500],
    "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
  },
  "createdAt": "2020-07-09T12:35:42.115395Z",
}

chain - Name of the registered chain
labels (optional) - List of custom labels. Useful to add custom information to the transaction.
params
- from - The address of the registered account.
- to - The address of the deployed smart contract.
- methodSignature - Signature of the method to execute on the deployed smart contract.
- args - List of arguments corresponding to the methodSignature.

Prevent duplicate transactions with an idempotency key

To prevent sending twice the same transaction, you can set an idempotency key as part of the header of the HTTP call. Setting an idempotency key is recommended as it will prevent sending duplicate transactions in the event of a failure to receive the response from Orchestrate Gateway API.

A transaction with the same idempotency key and different parameters will be rejected by Orchestrate Gateway API.
A transaction with the same idempotency key and parameters will be resent (but not duplicated).

Example

REST Request

curl --location --request POST 'https://orchestrate.consensys.net/transactions/send' \
--header 'X-Idempotency-Key: myIdempotencyKey'
--data '{...}'

JavaScript (SDK)

const request = {...}
const idempotencyKey = 'myIdempotencyKey';
const txResponse = await txClient.sendTransaction(request, idempotencyKey);

Set a gas price policy

Transactions can take a long time to be mined if their specified gas price is too low. Orchestrate can automatically resend the transaction by increasing its gas price until it is mined.

To define a gas price policy, fill the gasPricePolicy field in params.

Example

REST Request

{
...
    "gasPricePolicy": {
        "priority": "very-high",
        "retryPolicy": {
            "increment": 0.05,
            "interval": "2m",
            "limit": 0.5
        }
    },
}

JavaScript (SDK)

const txResponse = await txClient.sendTransaction({
  chain: 'myChain',
  labels: {
    property1: 'myLabel1',
    property2: 'myLabel2'
  },
  params: {
    ...
    gasPricePolicy: {
        priority: Priority.VeryHigh,
        retryPolicy: {
            increment: 0.05,
            interval: '2m',
            limit: 0.5
        }
    },
  },
});

priority - Priority of the transaction. Can be very-low, low, medium, high or very-high.
retryPolicy
- increment - Multiplier to increment the gas price every time the transaction is resent.
- interval - The amount of time to wait before resending a transaction with an increased gas price.
- limit - The multiplier limit. In the example above, the multiplier will reach the limit after 10 retries.

Send a private transaction

Orchestrate supports sending private transactions over a Besu or GoQuorum private network, allowing users to send confidential transactions that cannot be decoded by parties outside of the group chosen by the sender of the transaction.

Prerequisites

A registered chain.
A registered account (optional if using a one-time-key transaction).
A registered smart contract (mandatory for contract deployments).

Example

REST Request

{
  "chain": "myChain",
  "labels": {
    "property1": "myLabel1",
    "property2": "myLabel2"
  },
  "params": {
    "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
    "methodSignature": "transfer(address,uint256)",
    "args": ["0x0eeae27a0cbfb02945720425d3b80c7e09728534", 500],
    "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
    "privateFor": [
    "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
    "B1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo="
    ],
    "privateFrom": "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
    "protocol": "Tessera",
  }
}

JavaScript (SDK)

const txResponse = await txClient.sendTransaction({
  chain: 'myChain',
  labels: {
    property1: 'myLabel1',
    property2: 'myLabel2'
  },
  params: {
    methodSignature: 'transfer(address,uint256)',
    args: ['0x0eeae27a0cbfb02945720425d3b80c7e09728534', 500],
    to: '0xfffae27a0cbfb02945720425d3b80c7e09728534',
    from: '0x1abae27a0cbfb02945720425d3b80c7e09728534',
    privateFor: [
        'A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=',
        'B1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo='
    ],
    privateFrom: 'A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=',
    protocol: ProtocolType.Tessera,
  },
});

JSON response

{
  "uuid": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
  "chain": "myChain",
  "idempotencyKey": "myIdempotencyKey",
  "jobs": [
    {
      "uuid": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c"
      "chainUUID": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
      "labels": {
        "property1": "myLabel1",
        "property2": "myLabel2"
      },
      "logs": [...],
      "scheduleUUID": "b4374e6f-b28a-4bad-b4fe-bda36eaf849c",
      "status": "STARTED",
      "tenantID": "foo",
      "transaction": {
        "data": "0xfe378324abcde723...",
        "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
        "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
        "privateFor": [
            "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
            "B1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo="
        ],
        "privateFrom": "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
        "updatedAt": "2020-07-09T12:35:42.115395Z",
        "createdAt": "2020-07-09T12:35:42.115395Z",
      },
      "type": "eth://ethereum/transaction",
      "createdAt": "2020-07-09T12:35:42.115395Z",
      "updatedAt": "2020-07-09T12:35:42.115395Z",
    }
  ],
  "params": {
    "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
    "methodSignature": "transfer(address,uint256)",
    "args": ["0x0eeae27a0cbfb02945720425d3b80c7e09728534", 500],
    "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
    "privateFor": [
        "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
        "B1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo="
    ],
    "privateFrom": "A1aVtMxLCUHmBVHXoZzzBgPbW/wj5axDpW9X8l91SGo=",
    "protocol": "Tessera",
  },
  "createdAt": "2020-07-09T12:35:42.115395Z",
}

privateFrom - Address of the sender (Orion or Tessera node address, not an Ethereum address).
privateFor - List of participants of the transaction (Orion or Tessera node addresses, not Ethereum addresses).
privacyGroupId - Use a previously defined privacy group (only on Orion) instead of privateFor.
protocol - Tessera or Orion.

Send a private one-time-key transaction

In private networks where the gas price to send a transaction is 0, we recommend using one-time-key transactions to increase anonymity. Given that accounts do not need ETH to send transactions, they can be created on-the-fly.

To send a private one-time-key transaction, add "oneTimeKey": true to the params and remove the from field.