Skip to content
You are reading Codefi Orchestrate development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

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.

Example

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

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

curl --location --request POST 'https://orchestrate.consensys.net/transactions/send' \
--header 'X-Idempotency-Key: myIdempotencyKey'
--data '{...}'
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

{
...
    "gasPricePolicy": {
        "priority": "very-high",
        "retryPolicy": {
            "increment": 0.05,
            "interval": "2m",
            "limit": 0.5
        }
    },
}
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

Example

{
  "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",
  }
}
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,
  },
});
{
  "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.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can obtain paid professional support by Consensys at orchestrate@consensys.net