첫 PoE 게시하기

게시는 Label 309에서 게이트웨이가 실제로 필요한 절반입니다. 검증은 신뢰가 필요 없고 계정도 필요 없지만, 게시는 트랜잭션을 온체인에 기록하므로 수수료가 발생합니다. 그래서 트랜잭션을 구축하고 수수료를 지불하며 자체 잔액 모델에서 비용을 차감하는 Label 309 게이트웨이를 통해 제출하게 됩니다. SDK와 CLI는 게이트웨이에 종속되지 않으므로, API 키를 보유한 게이트웨이라면 어디로든 향하게 할 수 있습니다.

모든 게시는 동일한 2단계 형태입니다. 가격을 고정한 다음, 제출합니다. 게이트웨이는 실시간 FX 스냅샷을 기준으로 레코드의 가격을 산정하고 15분간 유효한 quote_id를 반환합니다. 게시 호출은 온체인 삽입과 함께 이 quote_id를 원자적으로 소비합니다. 상위 수준 헬퍼가 콘텐츠를 해시하고 정규 CBOR 레코드를 대신 구축해 줍니다.

CLI로

cardanowall 바이너리를 설치한 다음, submit을 파일로 향하게 합니다. 콘텐츠를 해시하고 다이제스트를 온체인에 기록한 뒤 결과를 출력합니다.

cardanowall submit \
  --file ./contract.pdf \
  --base-url https://your-gateway.example \
  --api-key "$CW_API_KEY"

--base-url과 --api-key는 환경 변수 CARDANOWALL_BASE_URL 및 CARDANOWALL_API_KEY, 또는 저장된 게이트웨이 프로파일에서도 읽어 오므로 CI에서는 명령에서 생략할 수 있습니다. 이미 다이제스트를 보유하고 있다면 --file 대신 --hash로 곧바로 기록하면 됩니다. 기본값 sha2-256에서 전환하려면 --alg blake2b-256을, 기계 판독이 가능한 요약을 원하면 --json을 추가하십시오.

cardanowall submit --hash 3b9f…c1a2 --json

레코드에 자신의 신원 키로 서명하려면 32바이트 마스터 시드를 --seed-file 또는 --seed-stdin을 통해 전달하십시오(--seed를 argv에 그대로 적으면 셸 기록에 남으므로 절대 사용하지 마십시오). 생략하면 서명 없이 게시됩니다.

TypeScript SDK로

게이트웨이를 대상으로 클라이언트를 생성한 다음, 한 번의 헬퍼 호출로 견적과 게시를 함께 수행합니다. publishContent는 바이트를 해시하고 레코드를 구축하여 제출합니다.

import { Label309Client } from '@cardanowall/sdk-ts';

const client = new Label309Client({
  baseUrl: 'https://your-gateway.example',
  apiKey: process.env.CW_API_KEY,
});

const quote = await client.poe.quote({
  recordBytes: 256,
  recipientCount: 0,
  fileBytesTotal: 0,
});

const result = await client.poe.publishContent({
  content: fileBytes, // Uint8Array or a UTF-8 string
  quoteId: quote.quote_id,
  // idempotencyKey: crypto.randomUUID(), // safe to retry the same submit
  // signer is optional — omit to publish unsigned (profile=core)
});

console.log(result.id, result.tx_hash, result.status);
console.log(result.balance_after_usd_micros); // decimal string of USD micro-cents

result.status는 처음에 submitting으로 시작합니다. 게이트웨이가 트랜잭션을 구축하기 전까지 tx_hash는 null입니다. idempotencyKey를 전달하면 재시도가 안전해집니다. 동일한 제출을 반복해도 원래 레코드가 반환되며(dedup_hit: true), 이중으로 차감되지 않습니다. 미리 계산한 다이제스트에는 publishPrehashed를, 수신자 봉인 봉투에는 publishSealed를 사용하십시오.

Python SDK로

cardanowall-sdk는 TypeScript 헬퍼와 메서드 단위로 대응합니다. 클라이언트는 비동기 컨텍스트 매니저이며, 응답은 일반 딕셔너리로 반환됩니다.

import asyncio
from cardanowall.client import Label309Client


async def main() -> None:
    async with Label309Client(
        base_url="https://your-gateway.example",
        api_key="<opaque-bearer>",
    ) as client:
        quote = await client.poe.quote(
            record_bytes=256, recipient_count=0, file_bytes_total=0
        )
        out = await client.poe.publish_content(
            content="hello world",  # str (UTF-8) or bytes
            quote_id=quote["quote_id"],
        )
        print(out["id"], out["tx_hash"], out["status"])


asyncio.run(main())

Rust SDK로

cardanowall 크레이트도 동일하게 게이트웨이에 종속되지 않는 클라이언트를 제공합니다. 호출은 블로킹 방식이므로 비동기 런타임이 필요 없으며, 헬퍼는 타입이 지정된 결과를 반환합니다.

use cardanowall::client::{
    Label309Client, Label309ClientConfig, PublishContentInput, QuoteInput,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Label309Client::new(Label309ClientConfig {
        base_url: Some("https://your-gateway.example".into()),
        api_key: std::env::var("CW_API_KEY").ok(),
    })?;

    let quote = client.poe().quote(&QuoteInput {
        record_bytes: 256,
        recipient_count: 0,
        file_bytes_total: 0,
    })?;

    let result = client.poe().publish_content(&PublishContentInput {
        content: file_bytes, // Vec<u8>
        quote_id: quote.quote_id,
        hash_alg: None, // defaults to sha2-256
        signer: None,   // omit to publish unsigned (profile = core)
        idempotency_key: None,
    })?;

    println!("{} {:?} {:?}", result.id, result.tx_hash, result.status);
    Ok(())
}

미리 계산한 다이제스트에는 publish_prehashed를, 수신자 봉인 봉투에는 publish_sealed를 사용하십시오.

수수료는 게이트웨이의 몫, 증명은 게시자의 것

게시에 사용한 게이트웨이가 Cardano 수수료를 지불하고 자체 잔액 모델에서 비용을 차감합니다. 하지만 그것이 기록하는 레코드는 라벨 309 아래에 놓인 순수한 Label 309 메타데이터입니다. 누구나 계정 없이, 게이트웨이에 대한 신뢰 없이도 공개된 체인만으로 검증할 수 있습니다. 대신 레코드를 수신자에게 보내려면 봉인된 PoE 만들기를, 정확한 온체인 구조에 대해서는 레코드를 참조하십시오.