> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zama decrypted transfers

> Stream ERC-7984 confidential transfers with decrypted amounts from the zama.decrypted_transfers dataset, using a delegate key that wallets authorize on-chain.

## Overview

[Zama](https://www.zama.ai/) confidential tokens (ERC-7984) hide transfer amounts on-chain. The `zama.decrypted_transfers` dataset lets Goldsky pipelines decrypt these transfers, as long as the delegate wallet key is stored in [Turbo secrets](https://docs.goldsky.com/turbo-pipelines/secrets.md) and, on mainnet, a Zama relayer API key is provided.

> [!NOTE]
>
> Wallets must grant decryption rights to your delegate address on-chain, through Zama's access control list, before the pipeline reads their transfers. Delegations are per token: a wallet must delegate on each token you want decrypted.

## Delegate key

The delegate key only signs EIP-712 decryption permits. It does not send transactions on your behalf or take any other on-chain action. For automated on-chain activity, see [Compose](https://docs.goldsky.com/compose/introduction.md).

> [!WARNING]
>
> **Goldsky strongly recommends a delegate wallet created only for Goldsky.** Your secrets are stored securely; this is a preventive measure.

## Goldsky Turbo vs self-hosted

Both modes use the same open-source plugin from [streamling-community-plugins](https://github.com/goldsky-io/streamling-community-plugins). On Turbo, Goldsky manages the decryption setup for you; self-hosted, you run it yourself.

| | Goldsky Turbo | Self-hosted |
| - | - | - |
| Pipeline shape | The `zama.decrypted_transfers` dataset | `erc7984_decode` and `zama_decrypt` transforms |
| Key reference | `secrets: { delegate_private_key: <SECRET_NAME> }` on the source | `delegate_private_key`, environment only |
| Where the key lives | A [Turbo secret](https://docs.goldsky.com/turbo-pipelines/secrets.md) in Goldsky's secrets backend | Wherever you keep your environment |

### Goldsky Turbo

Store the delegate key as a [turbo secret](https://docs.goldsky.com/turbo-pipelines/secrets.md):

```bash theme={"dark"}
goldsky secret create --name CUSTOM_SOURCE_SECRET \
  --value "{\"type\":\"turbo\",\"value\":\"$(cat delegate.key)\"}"
```

On mainnet, the Zama-hosted relayer also needs a relayer API key. [Apply to Zama for a key](https://docs.zama.org/protocol/sdk/guides/relayer-api-keys); Zama bills relayer usage to you directly. Store it as a turbo secret too:

```bash theme={"dark"}
goldsky secret create --name CUSTOM_API_KEY \
  --value "{\"type\":\"turbo\",\"value\":\"$(cat relayer.key)\"}"
```

The Sepolia relayer is open and needs no API key, so you can test the full flow on Sepolia first.

Any Turbo pipeline can read decrypted transfers from the `zama.decrypted_transfers` dataset:

```yaml theme={"dark"}
name: zama-decrypted-transfers
resource_size: s

sources:
  transfers:
    type: dataset
    dataset_name: zama.decrypted_transfers
    version: 1.0.0
    chain_id: 1
    start_at: latest
    # Optional: only decrypt these tokens (comma-separated): cUSDC, cUSDT
    tokens: "0xe978f22157048e5db8e5d07971376e86671672b2,0xae0207c757aa2b4019ad96edd0092ddc63ef0c50"
    # Maps plugin options to the turbo secrets that hold the credentials
    secrets:
      delegate_private_key: CUSTOM_SOURCE_SECRET
      # Required on mainnet; leave out on Sepolia
      relayer_api_key: CUSTOM_API_KEY

transforms: {}

sinks:
  output:
    # Prints each decrypted transfer to the pipeline logs
    type: print
    from: transfers
```

| Source option | Required | Description |
| - | - | - |
| `chain_id` | Yes | Chain to read and decrypt |
| `secrets` | Yes | `delegate_private_key` always. `relayer_api_key` on mainnet, where the Zama-hosted relayer requires it |
| `tokens` | No | Comma-separated token contracts to decrypt. Limits delegation lookups and relayer calls to these tokens. Rows of other tokens are still emitted, with null `zama_*` columns |
| `max_concurrency` | No | Relayer concurrency within one batch |
| `filter`, `columns` | No | Row filter and column projection, applied after decryption. Use `filter` to drop rows, not to limit decryption |

Goldsky stores both secrets and can read them. Treat the delegate key as readable by the platform, which is why it must be a dedicated, unfunded key. Goldsky holds no Zama credential of its own: the relayer API key is yours, and relayer usage is billed to you by Zama.

A pipeline holds one delegate key and one relayer API key, so every `zama.decrypted_transfers` source in it must map each option to the same secret. A `delegate_private_key` or `relayer_api_key` written directly in the YAML fails the deploy.

## Output columns

All input columns are kept, and three nullable string columns are added. In `zama.decrypted_transfers`, the input columns are:

* Block and transaction context, as in the [EVM logs schema](https://docs.goldsky.com/turbo-pipelines/reference/schema/EVM-schemas.md#logs).
* The decoded transfer: `token_address`, `from_address`, `to_address`, and `amount_handle` (the encrypted amount).

| Column | Content |
| - | - |
| `zama_amount` | Cleartext amount as a decimal string of the raw integer, not scaled by token decimals |
| `zama_delegator` | The wallet whose delegation was used |
| `zama_error` | Why `zama_amount` is null for a decoded transfer |

## Failure behavior

* A permanent refusal for one handle or one delegator is written to `zama_error`. The batch is still emitted and is not retried. To retry these rows, reprocess them from the raw logs by deploying a new pipeline with a new name.
* No active delegation is also a permanent answer: the row gets `no active delegation from either party`, and the transform re-checks that wallet only after 60 seconds. Confirm that a new delegation is visible on-chain before the pipeline reads its transfers, or reprocess the affected rows.

> [!TIP]
>
> Test before you deploy a long-running pipeline. Run a [job](https://docs.goldsky.com/turbo-pipelines/job-mode.md) over a known block range that holds transfers your delegate key can decrypt, and check `zama_amount` and `zama_error` in the output:
>
> ```yaml theme={"dark"}
> name: zama-decrypt-test
> resource_size: s
> job: true # required with end_at
>
> sources:
>   transfers:
>     type: dataset
>     dataset_name: zama.decrypted_transfers
>     version: 1.0.0
>     chain_id: 1
>     start_at: "FIRST_BLOCK" # a block with delegated transfers
>     end_at: LAST_BLOCK      # inclusive upper bound
>     tokens: "0xe978f22157048e5db8e5d07971376e86671672b2,0xae0207c757aa2b4019ad96edd0092ddc63ef0c50"
>     secrets:
>       delegate_private_key: CUSTOM_SOURCE_SECRET
>       relayer_api_key: CUSTOM_API_KEY
>
> sinks:
>   output:
>     type: print
>     from: transfers
> ```
>
> When the output looks right, deploy the permanent pipeline without `job` and `end_at`. Use `start_at: latest` for new transfers only, or set `start_at` to the first block you want decrypted, such as the token's deployment block, to backfill history. See [Controlling the block range](https://docs.goldsky.com/turbo-pipelines/sources/edge-evm.md#controlling-the-block-range) for `start_at` and `end_at`.

## Self-hosted

Run the plugin from [streamling-community-plugins](https://github.com/goldsky-io/streamling-community-plugins) and set the credentials in the environment. The plugin refuses to start if a credential is in the YAML, because Streamling logs plugin options at startup.

```bash theme={"dark"}
export STREAMLING__PLUGIN__ZAMA_DECRYPT__DELEGATE_PRIVATE_KEY=0xYOUR_DELEGATE_KEY
# Mainnet only: the Zama-hosted mainnet relayer requires an API key
export STREAMLING__PLUGIN__ZAMA_DECRYPT__RELAYER_API_KEY=YOUR_RELAYER_API_KEY
```

The self-hosted plugin also needs a running Zama SDK daemon on a Unix socket (`daemon_socket`), owned by the same user as Streamling. See the plugin README for daemon setup. The self-hosted transforms read logs that you decode with `erc7984_decode`, for example:

```yaml theme={"dark"}
transforms:
  decoded:
    type: erc7984_decode
    from: logs

  decrypted:
    type: zama_decrypt
    from: decoded
    chain_id: "1"
    rpc_url: https://YOUR_ETHEREUM_MAINNET_RPC
    daemon_socket: /tmp/zama-sdk/zama.sock
```

### Transform configuration

These are the `zama_decrypt` transform options (self-hosted). Any option can also be set as `STREAMLING__PLUGIN__ZAMA_DECRYPT__<KEY>` (uppercase key). The environment value wins.

| Option | Required | Default | Description |
| - | - | - | - |
| `chain_id` | Yes | | EVM chain ID. Selects the Zama relayer and contracts |
| `rpc_url` | Yes | | JSON-RPC endpoint for public reads |
| `secrets` | Goldsky Turbo | | Map of plugin options to turbo secrets you named, for example `delegate_private_key: CUSTOM_SOURCE_SECRET`. See [Turbo secrets](https://docs.goldsky.com/turbo-pipelines/secrets.md#use-a-secret-in-a-pipeline) |
| `delegate_private_key` | Self-hosted | | Hex secp256k1 delegate key. Environment only |
| `daemon_socket` | Self-hosted | | Absolute path of the Zama SDK daemon socket |
| `relayer_api_key` | Mainnet | | Zama relayer API key. Required by the Zama-hosted mainnet relayer; the Sepolia relayer needs none. Environment only |
| `tokens` | No | All | Comma-separated token contracts to decrypt. Other tokens pass through |
| `token_column` | No | `erc7984_token` | Column with the token contract |
| `from_column`, `to_column` | No | `erc7984_from`, `erc7984_to` | Columns with the transfer parties |
| `handle_column` | No | `erc7984_amount_handle` | Column with the encrypted amount handle |
| `max_concurrency` | No | SDK default | Relayer concurrency within one batch |


## Related topics

- [Turbo secrets](https://docs.goldsky.com/turbo-pipelines/secrets.md)
- [Turbo pipeline sources: EVM, Solana, Stellar, NEAR, Bitcoin](https://docs.goldsky.com/turbo-pipelines/sources/overview.md)
- [Transfers](https://docs.goldsky.com/feeds/api/transfers.md)
- [Native transfers](https://docs.goldsky.com/turbo-pipelines/guides/token-transfers/native-transfers.md)
- [Stablecoin transfers](https://docs.goldsky.com/turbo-pipelines/guides/token-transfers/stablecoin-transfers.md)
