Documentation

Python 0.2.0 helpers for GIWA transactions, signing, events, and metadata verification.

The checked-in mosaic-sdk source is version 0.2.0. It exports MosaicClient, GIWA Sepolia deployment constants, event decoding, and metadata helpers. This page describes that source version without making a package-registry publication claim.

Import

from mosaic_sdk import (
    GIWA_SEPOLIA_CHAIN_ID,
    GIWA_SEPOLIA_MOSAIC_BOUNTIES_ADDRESS,
    GIWA_SEPOLIA_RPC_URL,
    GIWA_SEPOLIA_TEST_USDC_ADDRESS,
    MosaicClient,
    canonical_metadata_hash,
    decode_event,
    load_metadata,
)

GIWA Sepolia Defaults

MosaicClient() defaults to the active GIWA Sepolia deployment:

Field	Value
`chain_id`	`91342`
`rpc_url`	`https://sepolia-rpc.giwa.io`
`contract_address`	`0x7ebC4d9EfA037dFaAfBB80025A09B249eCFf4F84`
`usdc_address`	`0x25ceeBa0a118DA5C346a5328D7cC5f26aa331d17`

client = MosaicClient()

For another deployment, provide chain_id, contract_address, and usdc_address together. rpc_url may also be overridden. Partial deployment configuration raises ValueError.

client = MosaicClient(
    rpc_url="https://rpc.example",
    chain_id=12345,
    contract_address="0x1111111111111111111111111111111111111111",
    usdc_address="0x2222222222222222222222222222222222222222",
)

Transaction Shape

Builders return transaction dictionaries for the configured chain. The default client returns:

{
    "chainId": 91342,
    "to": "0x...",
    "data": "0x...",
    "value": 0,
}

Transaction Helpers

Method	Contract Call
`approve_usdc(amount)`	USDC `approve(contractAddress, amount)`
`create_bounty(metadata_uri, metadata_hash, reward_amount, duration)`	`createBounty(string,bytes32,uint256,uint64)`
`submit(bounty_id, metadata_uri, metadata_hash)`	`submit(uint256,string,bytes32)`
`dispute(submission_id, metadata_uri, metadata_hash)`	`dispute(uint256,string,bytes32)`
`finalize(bounty_id)`	`finalize(uint256)`
`advance_review_cursor(bounty_id)`	`advanceReviewCursor(uint256)`
`resolve_dispute(challenge_id, accepted)`	`resolveDispute(uint256,bool)`
`refund_expired(bounty_id)`	`refundExpired(uint256)`
`refund_submission_bond(submission_id)`	`refundSubmissionBond(uint256)`
`cancel_resolved_dispute(challenge_id)`	`cancelResolvedDispute(uint256)`
`withdraw()`	`withdraw()`
`withdraw_to(recipient)`	`withdrawTo(address)`

resolve_dispute requires the configured contract admin. Other methods remain subject to their contract role and state checks.

Sign And Send

Configure a private key to use send(tx). The client validates the transaction and RPC chain IDs, obtains nonce and gas values, signs locally, and broadcasts with eth_sendRawTransaction.

client = MosaicClient(private_key="0x...")
approve = client.approve_usdc(50_125_000)
tx_hash = await client.send(approve)

Without private_key, send raises ValueError("private key required to send transaction").

Admin Helpers

These builders require contract admin authority:

Method	Contract Call
`set_config(min_reward_amount, bond_bps, post_fee_bps, review_window, fee_recipient)`	`setConfig(uint256,uint16,uint16,uint64,address)`
`set_allowed_duration(duration, allowed)`	`setAllowedDuration(uint64,bool)`
`set_grout(grout, allowed)`	`setGrout(address,bool)`
`set_admin(admin)`	`setAdmin(address)`

Event Decoding

decode_event(log) decodes supported Mosaic contract logs into a dictionary containing the event name and decoded fields.

event = decode_event(log)
print(event["name"])

Metadata Helpers

metadata = await load_metadata(
    "ar://bounty-json",
    expected_hash="0x1111111111111111111111111111111111111111111111111111111111111111",
)

canonical_metadata_hash(metadata) hashes sorted compact JSON with Keccak.

load_metadata(uri, expected_hash=None, gateway="https://arweave.net") fetches HTTP URLs directly. For ar:// URIs, it prefixes the configured gateway. When expected_hash is set, it raises ValueError("metadata hash mismatch") on mismatch.

Inputs

Amount arguments are integers in USDC base units.
Metadata hash arguments must encode to 32 bytes.
Addresses are normalized to checksum addresses while building transactions.

Python SDK