1. これは何？

STN（Symbol Transaction Notation） は、Symbolのトランザクションを
1行の短い文字列で表現するための記法です。

図を描かなくても、文章で長く説明しなくても
「誰が・誰に・何をする」 が一目で分かります。
特に、複数の処理をまとめる アグリゲートトランザクションや、
マルチシグのような複雑な構造を、簡潔に表せます。

2. 何が嬉しい？

STNを使うと、例えば提案書や議事メモでこうなります。

「このTxは複雑なので図で…」→ 不要
「これTransfer？Metadata？」→ 一発で判別できる
「アグリゲートの中身を列挙して」→ そのまま1ブロックで書ける

さらに、STNは 機械で解析してグラフ化もできます。
（テキストを入れるだけで、関係図を自動生成できます）

3. まず一番大事な基本

3.1 送金（TransferTransaction）は省略形がデフォルト

もっとも頻出する送金は、記法を最短にしています。

Alice>Bob[1:xym]@message

意味：
Alice が Bob に 1 XYM を送る（メッセージ付き）

記号の読み方

Alice > Bob ：Alice から Bob へ
[1:xym] ：1 XYM
@message ：メッセージ（任意）

3.2 複数の資産を同時に送る

Alice>Bob[1:xym,1:nft]@message

意味：
Alice が Bob に「1 XYM と 1 NFT」を送る

, は「同時に複数」の区切りです

4. マルチシグ（複数人承認）を表す

4.1 マルチシグ送金

Alice{@Bob,Carol,Dave}[2/3]>Ellen[1:xym]@message

意味：
「Alice」はマルチシグアカウント。
Bob / Carol / Dave のうち 2人の承認が必要。
その上で Ellen に 1 XYM を送る。

記号の読み方

Alice{...}[2/3]：Aliceはマルチシグ、2/3の承認が必要
{Bob,Carol,Dave}：承認者の候補
{@Bob,...}：@付きが“起案者（イニシエータ）”の表現（任意）

※この記法は「トランザクションの構造」を説明するもので、
実際の承認手順（署名収集）までは描きません。

5. アグリゲート（複数Txを1つにまとめる）

5.1 アグリゲートの基本形

[
  Tx1,
  Tx2
]@Bob

意味：
複数の処理（Tx1, Tx2）をひとまとめにし、
全体の起案者（イニシエータ）は Bob。

アグリゲートは 中身が2つ以上になるので
[] でまとめ、, で区切ります。

5.2 具体例（2つの送金をまとめる）

[
  Alice{Bob,Carol,Dave}[2/3]>Ellen[1:xym]@message,
  Ellen>Alice[1:xym]@message
]@Bob

意味：

マルチシグAliceからEllenへ1XYM
EllenからAliceへ1XYM
この2つをセットでまとめたアグリゲート
起案者は Bob

6. 送金以外のトランザクションは明示する

送金（Transfer）だけが省略形です。
それ以外は必ず transactionType# を書きます。

6.1 メタデータ（Metadata）

Alice>metadata#Bob[id:key]@xorMessage

意味：
Alice が Bob に対してメタデータ操作を行う。
キーは id:key。メッセージは xorMessage。

ここがポイント

metadata#Bob のように
トランザクション種別 + 対象を # で接着して書きます
Transfer以外は「必ず明示」なので誤読しません

7. まとめ：最小ルール（これだけ覚えれば読める）

A>B[...] は送金（Transfer）
送金以外は type#target を書く
アグリゲートは [...]@Bob（中は,区切り）
マルチシグは Alice{...}[m/n]

8. 応用：STNはグラフ化できる

STNは「記号の位置が固定」なので、
ツールで読み取って 自動で関係図を生成できます。

提案書：テキストで書く
説明資料：同じ内容をグラフでも出す
という運用が可能です。

9. YAML仕様

AIにSTNを理解させるには以下のYAMLを読み込ませてください。

schema: STN
full_name: Symbol Transaction Notation
version: 0.1
purpose: >
  One-line notation to express Symbol transactions,
  including transfer, multisig, and aggregate structures,
  in a form instantly parseable by humans and machines.

defaults:
  transaction_type:
    omitted_means: transfer
  asset_separator: ","
  aggregate_separator: ","

entities:
  Account:
    description: Symbol account identifier (string)
  Asset:
    format: "<amount>:<namespace>"
    example: "1:xym"

syntax:
  arrow: ">"
  message_prefix: "@"
  type_separator: "#"
  aggregate_open: "["
  aggregate_close: "]"
  multisig_open: "{"
  multisig_close: "}"
  approval_format: "[m/n]"

transaction_types:
  transfer:
    default: true
    syntax: "FROM>TO[assets]@message?"
    example: "Alice>Bob[1:xym]@message"

  metadata:
    syntax: "FROM>metadata#TARGET[key]@value"
    example: "Alice>metadata#Bob[id:key]@xorMessage"

multisig:
  syntax: "ACCOUNT{cosigners}[m/n]"
  rules:
    - cosigners_are_accounts: true
    - approval_required: m_of_n
    - initiator_optional: true
  initiator_mark:
    symbol: "@"
    meaning: "aggregate initiator hint"
  example: "Alice{@Bob,Carol,Dave}[2/3]"

aggregate:
  syntax: "[Tx1,Tx2,...]@INITIATOR"
  rules:
    - minimum_inner_transactions: 2
    - inner_transactions_ordered: true
    - initiator_single: true
  example: |
    [
      Alice{Bob,Carol,Dave}[2/3]>Ellen[1:xym]@message,
      Ellen>Alice[1:xym]@message
    ]@Bob

parsing_rules:
  precedence:
    - aggregate
    - multisig
    - transaction_type
    - transfer
  transfer_is_default: true
  non_transfer_requires_type: true

semantic_mapping:
  ">":
    meaning: "from_to_relation"
  "#":
    meaning: "explicit_transaction_type"
  "@":
    meaning:
      - message
      - aggregate_initiator
  ",":
    meaning: "parallel_assets_or_transactions"

machine_properties:
  deterministic: true
  graph_convertible: true
  loseless_to_symbol_sdk: true

design_goals:
  - readable_in_plain_text
  - writable_in_meeting_notes
  - convertible_to_graph
  - auditable_structure
  - minimal_symbols