Contractless/docs/MARKETING_TRANSACTIONS.md

# Marketing Transactions

Marketing transactions are native Contractless records intended for marketing and advertising agencies. They let an agency record campaign activity on chain so a customer can later verify impressions, clicks, display locations, keywords, campaign identifiers, and related value fields.

There is one CLI tool for creating marketing records:

```text
create_marketing_tx
```

On Windows, add `.exe` to the command name.

When a tool asks for a wallet path, press `<Tab>` to search and auto-complete files and folders.

## Purpose

Marketing records are designed for campaign reporting.

Example uses:

- Record that an ad was displayed on a specific URL.
- Record impressions and clicks for a campaign.
- Record the keyword or targeting term associated with an impression/click record.
- Record impression and click values for later customer reporting.
- Let a customer verify that a marketing agency recorded activity on chain.

The `advertiser` field is the agency or reporting wallet that signs and pays for the record. It is not necessarily the customer wallet.

## Lookup Notes

There is no dedicated marketing lookup CLI tool.

To inspect marketing records from CLI tools, use general transaction lookup flows:

- Look up a known marketing transaction hash.
- Look up transactions for an address and filter for marketing transaction records.

The customer generally needs to know either:

- The transaction hash of the marketing record, or
- The address of the agency/reporting wallet and enough context to filter its marketing transactions.

## Transaction Type

Marketing transactions are transaction type `5`.

## Transaction Fields

| Field | Size | Meaning |
| --- | ---: | --- |
| `txtype` | 1 byte | Transaction type. For marketing records this is `5`. |
| `time` / `timestamp` | 4 bytes | UTC timestamp when the transaction is created. |
| `campaign` | 8 bytes | Numeric campaign identifier. |
| `ad_type` | 6 bytes | Campaign type. Must be `banner`, `social`, or `text`, padded to 6 bytes. |
| `keyword` | 40 bytes | Keyword or targeting term, padded to 40 bytes. |
| `displayed` | 100 bytes | Display location, usually a URL or placement identifier, padded to 100 bytes. |
| `impression` | 1 byte | Impression count update, `0` to `255`. |
| `click` | 1 byte | Click count update, `0` to `255`. |
| `impression_value` | 2 bytes | Value per impression multiplied by `100`. |
| `click_value` | 2 bytes | Value per click multiplied by `100`. |
| `advertiser` | 22 bytes | Agency/reporting wallet short address. |
| `txfee` | 8 bytes | Base-currency transaction fee. Minimum is `1` CLC or CLTC. |
| `signature` | 666 bytes | Advertiser signature. |

## create_marketing_tx

Use `create_marketing_tx` to create and sign a marketing transaction.

Usage:

```text
create_marketing_tx
```

The tool writes the signed transaction JSON under:

```text
./transactions/<hash>.json
```

Saving the file does not broadcast it. Submit the saved transaction with `broadcast_transaction` or another normal transaction broadcast flow.

## Prompts

`create_marketing_tx` asks for:

| Prompt | What To Enter |
| --- | --- |
| Campaign ID | Numeric campaign identifier. |
| Campaign type | `banner`, `social`, or `text`. |
| Keyword | Keyword or targeting term, up to 40 characters. |
| Displayed location | URL, placement, or display location, up to 100 characters. |
| Views | Impression count for this record, `0` to `255`. |
| Clicks | Click count for this record, `0` to `255`. |
| Impression value | Decimal value for each impression, such as `1.25`. |
| Click value | Decimal value for each click, such as `1.25`. |
| Fee | Minimum `1` CLC or CLTC. |
| Wallet path | Agency/reporting wallet path. |
| Wallet key | Wallet decryption key. |

The tool pads fixed-width text fields automatically before signing:

- `ad_type` is padded to 6 bytes.
- `keyword` is padded to 40 bytes.
- `displayed` is padded to 100 bytes.

## Campaign ID

`campaign` is a numeric ID chosen by the advertiser/agency.

The chain does not define campaign meaning. An agency may use:

- A customer account number.
- An internal campaign number.
- A campaign/ad group ID from another system.
- A manually assigned reporting ID.

Customers should confirm with the agency which campaign ID should be tracked.

## Ad Type

`ad_type` must be one of:

```text
banner
social
text
```

The field is fixed at 6 bytes. `banner` and `social` already fill 6 bytes. `text` is padded with two spaces by the tool.

## Keyword

`keyword` is a 40-byte field. It can be a search term, targeting category, content keyword, placement keyword, or another short campaign descriptor.

Examples:

```text
blockchain wallet
testnet node
summer sale
```

## Displayed Location

`displayed` is a 100-byte field for where the ad was displayed.

Common values:

- A URL.
- A website domain.
- A social platform placement.
- An ad slot identifier.
- A newsletter or publisher placement ID.

Example:

```text
https://example.com/article/123
```

If the location is longer than 100 characters, shorten it before creating the transaction.

## Impressions And Clicks

Each marketing transaction records one update, not an entire campaign database.

`impression` is an unsigned byte, so one transaction can record `0` through `255` impressions.

`click` is also an unsigned byte, so one transaction can record `0` through `255` clicks.

Large campaigns should be recorded as multiple marketing transactions over time.

## Impression And Click Values

The CLI asks for decimal values and stores each value multiplied by `100`.

Example:

```text
Entered impression value: 1.25
Stored impression_value: 125

Entered click value: 2.50
Stored click_value: 250
```

This keeps value fields compact while preserving two decimal places.

The chain records the values supplied by the advertiser. It does not independently verify market price, invoice terms, or whether the agency's claimed value is fair. Customers should compare on-chain records to their agreement with the agency.

## Fees And Signing

The advertiser wallet signs the transaction and pays the base-currency fee.

Validation requires:

- Advertiser address is valid.
- Advertiser address is registered.
- Signature matches the advertiser wallet.
- Fee is at least `1` CLC or CLTC.
- Advertiser has enough base currency for the fee.
- `ad_type` is `banner`, `social`, or `text`.
- `keyword` is exactly 40 bytes after padding.
- `displayed` is exactly 100 bytes after padding.
- Transaction hash has not already been saved on chain.

## Output Shape

The saved JSON looks like:

```json
{
  "txtype": 5,
  "timestamp": 1780000000,
  "campaign": 12345,
  "ad_type": "banner",
  "keyword": "blockchain wallet                       ",
  "displayed": "https://example.com/article/123                                                                     ",
  "impression": 100,
  "click": 5,
  "impression_value": 125,
  "click_value": 250,
  "advertiser": "advertiser_short_address.cltc",
  "txfee": 100000000,
  "hash": "transaction_hash",
  "signature": "advertiser_signature"
}
```

In this example:

- `impression = 100`
- `click = 5`
- `impression_value = 125`, meaning `1.25`
- `click_value = 250`, meaning `2.50`
- `txfee = 100000000`, meaning `1` CLC or CLTC

## Customer Verification

A customer verifying campaign records should ask the agency for:

- Agency wallet address.
- Campaign ID.
- Expected ad types.
- Expected display URLs or placements.
- Expected keywords.
- Relevant transaction hashes, if available.

The customer can then inspect the agency's marketing transactions and compare:

- `campaign`
- `ad_type`
- `keyword`
- `displayed`
- `impression`
- `click`
- `impression_value`
- `click_value`
- transaction timestamp

Because the transaction is signed by the advertiser wallet, the customer can verify that the agency wallet recorded the campaign activity on chain.