From f7df2682a7a4423d4e907eeb56a6deade230d5dd Mon Sep 17 00:00:00 2001 From: contractless Date: Sun, 12 Jul 2026 19:21:29 +0000 Subject: [PATCH] Add docs/MARKETING_TRANSACTIONS.md --- docs/MARKETING_TRANSACTIONS.md | 263 +++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/MARKETING_TRANSACTIONS.md diff --git a/docs/MARKETING_TRANSACTIONS.md b/docs/MARKETING_TRANSACTIONS.md new file mode 100644 index 0000000..d7fdf19 --- /dev/null +++ b/docs/MARKETING_TRANSACTIONS.md @@ -0,0 +1,263 @@ +# 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 `` 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/.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. +