# Startpoint Called

Triggers when a contract invokes the `callMidpoint` function on a Midpoint-deployed Startpoint contract. 

Startpoint Called is used to trigger a midpoint from on-chain by making a call to the `callMidpoint` function in a Midpoint-deployed contract. Startpoint Called is used when creating oracles, data bridges, or any other workflow that begins with a contract on chain 'initiating' the workflow. 

## Using a Startpoint

Every chain has one Startpoint contract with the following two public functions:

```solidity
interface IMidpoint {
    function callMidpoint(uint64 midpointId) external returns(uint64 requestId);
    function callMidpoint(uint64 midpointId, bytes calldata _data) external returns(uint64 requestId);
}
```

A Startpoint is triggered by invoking a call to the `callMidpoint` function and passing the [Midpoint ID](https://docs.midpointapi.com/midpoint-documentation/core-concepts/midpoints/midpoint-id) and optionally passing in a packed byte array `_data`.  The startpoint contract will assign and return a globall unique [Request ID](https://docs.midpointapi.com/midpoint-documentation/core-concepts/requests/request-id) to the caller. This can be used to associate a response transaction with the originating call.

Startpoints currently support `intN`, `uintN`, `boolean`, `address`, and `string` Solidity types.

### Packing \_data

The Startpoint contract expects all of the passed parameters (defined in `variables`) to be packed according to the following specification.

1. Parameters are packed with Solidity's `abi.encodePacked()`.
2. Parameters are ordered according to the order defined in the StartpointCalledSource definition.
3. Each string is followed by a Null byte, indicated with `bytes1(0x00)`
4. No additional values are added to `_data`

Examples:

* A StartpointCalledSource is expecting a single `int256` valued called X.

```solidity
IMidpoint(startpointAddress).callMidpoint(midpointID, abi.encodePacked(X));
```

* A StartpointCalledSource is expecting two `string` values called Y and Z.

```solidity
bytes args = abi.encodePacked(Y, bytes1(0x00), Z, bytes1(0x00));
IMidpoint(startpointAddress).callMidpoint(midpointID, args);
```

* A StartpointCalledSource is expecting three variables in the following order: a `uint256` called A, a `string` called B and a `boolean` called C.

```solidity
bytes args = abi.encodePacked(A, B, bytes1(0x00), C);
IMidpoint(startpointAddress).callMidpoint(midpointID, args);
```

* A StartpointCalledSource is expecting no variables.

```solidity
IMidpoint(startpointAddress).callMidpoint(midpointID);
```

See [Startpoints](https://docs.midpointapi.com/midpoint-documentation/more-reading/startpoints) for detailed information on the Startpoint contract and deployed startpoing addresses.

## Definition

```graphql
whitelist:[ 
  {
    chainId: string
    contractAddress: string
  }
]
variables:[ 
  {
    name: string
    datatype: string
  }
]
extracts: [
  {
    name: string
    from: string
  }
]
excludeLogs: [string]
```

**`whitelist`: Array of {string, string}.** Array of chainId - contractAddress pairs. The Startpoint only listens for invocations to `callMidpoint` that come from a whitelisted chainId and contractAddress pair. A single Startpoint Called source may listen for calls from multiple contracts and chains simultaneously. 

**`whitelist.chainId`: See** [**Chain IDs**](https://docs.midpointapi.com/midpoint-documentation/more-reading/chain-ids)**.**

**`whitelist.contractAdddress`: Ethereum Address.** A valid 40-character Ethereum address prepended with `0x`. Example: `0xEf1c6E67703c7BD7107eed8303Fbe6EC2554BF6B`

**`variables`: Array of {string, string}.** Ordered array of variables that are expected to be passed from on-chain when this midpoint is called.

**`variables.name`: String.**The name to be assigned to this variable for use in future tasks.

**`variables.datatype`: Enum\[uintN, intN, boolean, string, address].** The Solidity type expected to be passed from on-chain. example: `uint256`

**`extracts`: See** [**extracts**](https://docs.midpointapi.com/midpoint-documentation/core-concepts/midpoints/source-and-task-definitions/extracts)**.** Legal values:

* **`Timestamp`** Unixtime of execution.
* **`Midpoint_ID`** See [Midpoint ID](https://docs.midpointapi.com/midpoint-documentation/core-concepts/midpoints/midpoint-id).
* **`Request_ID`** See [Request ID](https://docs.midpointapi.com/midpoint-documentation/core-concepts/requests/request-id).
* **`Contract_Address`** The contract address that invoked the call to the Startpoint. 
* **`Chain_ID`** The chain ID where the Startpoint was called.
* **`Block_Number`** The block number containing the transaction making the call.
* **`Txn_Hash`** The transaction hash of the transaction making the call.
* **`Txn_Origin`** The EOA that initiated the transaction that made the call.

**`excludeLogs`: See** [**exclude logs**](https://docs.midpointapi.com/midpoint-documentation/core-concepts/midpoints/source-and-task-definitions/exclude-logs)**.** Legal values: 

* **`TaskDefinition`** The complete definition of this task at runtime.

## Returned Values

The Startpoint Called source returns each of the variables listed under the `variables` field for use in future tasks - in addition to each field specified in `extracts`.

## Examples

This section is incomplete.

## Tips on Using Startpoint Called

This section is incomplete.