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:

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:

create_marketing_tx

The tool writes the signed transaction JSON under:

./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:

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:

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:

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:

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:

{
  "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.