Skip to main content

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​

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.

{
  "chain": "myChain",
  "contractName": "MyERC20"
  "contractTag": "v1.0.0",
  "labels": {
    "property1": "myLabel1",
    "property2": "myLabel2"
  },
  "params": {
    "from": "0x1abae27a0cbfb02945720425d3b80c7e09728534",
    "methodSignature": "transfer(address,uint256)",
    "args": ["0x0eeae27a0cbfb02945720425d3b80c7e09728534", 500],
    "to": "0xfffae27a0cbfb02945720425d3b80c7e09728534",
  }
}
  • chain - Name of the registered chain.
  • contractName - Name of the [registered contract].
  • contractTag (optional) - Tag of the [registered contract]. The default is latest.
  • labels (optional) - List of custom labels. Useful to add custom information to the transaction.
  • params
    • from - Address of the registered account.
    • to - 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 prevents 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 is rejected by Orchestrate Gateway API.
  • A transaction with the same idempotency key and parameters is resent (but not duplicated).
curl --location --request POST 'https://orchestrate.consensys.net/transactions/send' \
--header 'X-Idempotency-Key: myIdempotencyKey'
--data '{...}'

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, specify your preferences in the gasPricePolicy object in params.

{
...
    "gasPricePolicy": {
        "priority": "very-high",
        "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 - Amount of time to wait before resending a transaction with an increased gas price.
    • limit - Multiplier limit. In this example, the multiplier reaches 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​

REST Request

{
  "chain": "myChain",
  "contractName": "MyERC20"
  "contractTag": "v1.0.0",
  "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',
  contractName: 'MyERC20'
  contractTag: 'v1.0.0',
  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 (EEA or Tessera node address, not an Ethereum address).
  • privateFor - List of participants of the transaction (EEA or Tessera node addresses, not Ethereum addresses).
  • privacyGroupId - Use a previously defined privacy group (only on EEA) instead of privateFor.
  • protocol - Tessera or EEA.

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.