Skip to content
sayweerPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

C-Sign: signed messages for Stellar contract accounts

Status: draft specification (SPEC v0.0.2), reference verifier deployed on testnet (mainnet script ready, not run yet), TypeScript library 0.3.0 for C… and G… sign-in (npm release pending), 25 testnet experiments rerun weekly in CI, a threat model, an end-to-end quickstart and a passkey sign-in demo. The library has not been audited.

Live demo: c-sign-demo.vercel.app (testnet)

Read the project overview first, then the draft specification.

C-Sign lets a Stellar contract account (a C… address: passkey wallets, multisig accounts, agent wallets with spending policies) sign a human-readable message, and lets anyone verify that signature against the account's current on-chain rules, without submitting a transaction and without paying a fee. It is the counterpart of SEP-53 for contract accounts, discussed in stellar-protocol#2045 (earlier in issue #2027).

How it works

  1. The relying party asks for a message. It gives a statement and a one-time nonce. The wallet fills in the relying party's domain from the requesting origin, so a site cannot obtain a signature addressed to another site.
  2. The wallet signs an authorization entry. The account authorizes exactly one call, verify_message(account, msg), on an instance of the reference verifier contract. No sub-calls, V2 address credentials. The wallet shows the domain and statement decoded from that entry.
  3. The verifier never succeeds. It calls account.require_auth() and then always fails with the reserved error AuthOk. A signature submitted on-chain has no effect and the host rolls its nonce back, so it stays verifiable.
  4. The relying party verifies by simulation. It rebuilds the expected call, checks that the verifier instance runs the reference Wasm (by hash), and runs simulateTransaction in enforcing mode. The account's own __check_auth decides against its current signers, thresholds and policies. The result is valid, invalid or inconclusive.

There is no canonical verifier address. Anyone can deploy the reference Wasm; wallets and relying parties trust an instance only if its executable hash matches the published one.

Reference verifier

contracts/verifier/WASM_HASH = 2a5004a7736327a994d449af03ae7c5eea481da2d2d3191222dc7b4934a4c299

One function, no admin, no storage, no upgrade path. The message is a symbol-keyed map that the contract never reads, so new optional message fields never change the Wasm or its hash.

Testnet deployments

Two independent instances of the same Wasm, to show that none is canonical. Both run the pinned hash above. Details in deployments/testnet.json; scripts/deploy-testnet.sh checks the hash, skips what exists, extends TTLs and redeploys after a testnet reset.

Contract Id Wasm hash
Reference verifier, instance A CCL5EDN2…NFD5 2a5004a7…c299
Reference verifier, instance B CDWCB2Z3…XKJS 2a5004a7…c299
Fake verifier (experiment fixture, never trust) CBMSJ7WO…IIYQ f0b60332…c2d9
Non-reverting verifier (experiment fixture) CCZNVR6C…3LS4 4a0afd7e…de34

The fake verifier skips require_auth and still returns AuthOk; it shows that a relying party that does not pin the Wasm hash can be fooled. The non-reverting verifier succeeds after require_auth; it shows the nonce burn that the reference design avoids.

Mainnet: not deployed yet. IDENTITY=<funded identity> scripts/deploy-mainnet.sh deploys two instances of the reference verifier (no fixtures), checks the built and the deployed hashes, extends TTLs and writes deployments/mainnet.json. It never creates or funds an identity and asks for confirmation before spending XLM. Any instance running the pinned hash is as good as these two.

Quickstart

The package is not on npm yet; 0.3.0 is ready and will be published as c-sign. Until then, build it from this repository:

git clone https://github.com/sayweer/c-sign && cd c-sign
pnpm install && pnpm --filter c-sign build

Once it is published:

npm install c-sign
import { MemoryNonceStore, createSignInMessage, verifySignIn, TESTNET } from "c-sign";

const nonces = new MemoryNonceStore();

// GET /challenge: the message the wallet signs
const message = createSignInMessage({ domain: "example.com", statement: "Sign in to Example", ...nonces.issue() });

// POST /verify: the base64 entry the wallet returns
const result = await verifySignIn({
  signature,
  rpcUrl: TESTNET.rpcUrl,
  networkPassphrase: TESTNET.networkPassphrase,
  domain: "example.com",           // your own domain, from configuration
  nonces,
});
// result.status: "valid" | "invalid" | "inconclusive", result.steps: every check with its outcome

G… accounts sign in through the same verifySignIn with SEP-53 (details). examples/quickstart runs the whole flow on testnet in two terminals: a relying party in two framework-independent handlers and a wallet that creates a smart account and signs in. The library works in Node.js, browsers and edge runtimes, and next to stellar-sdk 16 or 17; see the library README.

verifySignIn implements the checks of SPEC §6 in order and never throws: rule violations are invalid, RPC failures and archived entries are inconclusive. verifyMessage runs the same checks without the nonce, for auditors and services that are not logging anyone in; domain: null skips the domain check for inspection tools. Its result is not a sign-in. buildMessageEntry builds the entry a wallet signs; checkMessageRequest is what a wallet runs before signing one (origin, entry shape, verifier pin); signOzMessageWithEd25519 signs it for an OpenZeppelin account with Ed25519 signers; its required scheme argument is the account's digest format, "preimage-v1" for stellar-accounts 0.8.0 and later or "legacy-concat" for 0.7.x. For passkey-kit wallets, signMessageWithPasskeyKit signs through a kit instance and signPasskeyKitMessageWithEd25519 signs with Ed25519 keys and no kit. Passkey signing on OpenZeppelin accounts uses smart-account-kit's signAuthEntry.

Evidence

docs/EXPERIMENTS.md is generated by pnpm e2e against testnet with fresh OpenZeppelin smart accounts. Highlights:

  • A valid signature submitted on-chain fails and leaves the nonce unused; the same signature still verifies afterwards. The on-chain trace shows the account's __check_auth accepting it and the verifier raising Error(Contract, #1). A verifier that succeeds instead burns the nonce.
  • A fake verifier lets anyone "sign" for any account when the Wasm hash is not pinned; pinning rejects it.
  • Tampered messages, other domains, other accounts, expired signatures and replayed nonces are rejected.
  • After a key rotation the old signature stops verifying and the new key's signature verifies.
  • A 2-of-3 threshold policy decides as well: after the threshold is raised to three, the same two-key signature stops verifying.
  • A minimal non-OpenZeppelin account, which signs the raw payload, verifies through the same path.
  • An OpenZeppelin stellar-accounts 0.8.0 account verifies with its new auth digest, rejects the old one, and computes the same digest on-chain as the library.
  • passkey-kit 0.14 and 0.20 wallets verify through the same path, with a software P-256 authenticator, and a recovery key limited to the wallet contract is invalid (docs/EXPERIMENTS-PASSKEY-KIT.md, pnpm --filter c-sign-kit-compat e2e).
  • The host accepts statements of about 190 KB, with or without a policy; only the RPC's request-size cap stops verification.
  • Median verification time against a public testnet RPC is under one second.

vectors/c-sign-v1.json holds language-neutral test vectors for other implementations: message encoding, the unsigned entry and its signature payload, OpenZeppelin signing (one signer and 2-of-3, with the digests of stellar-accounts 0.7.x and 0.8.0), the checks of SPEC §6 (offline, and against a stated RPC state for the verifier pin and the simulation decision) and the domain a wallet derives from an origin (§5). They follow SPEC v0.0.2 and the library passes every case. They are deterministic, generated by pnpm vectors and checked in CI.

Demo

c-sign-demo.vercel.app, source in apps/demo: create an OpenZeppelin smart account with a passkey, sign in without a transaction, then rotate the key and watch the first signature turn invalid. Every check is shown as it runs. See apps/demo/README.md to run or deploy it.

Repository layout

contracts/verifier/                   reference verifier (Rust, soroban-sdk 28) and its pinned Wasm hash
packages/c-sign/                      TypeScript library: message, entry, verifyMessage, OpenZeppelin and passkey-kit signing
packages/c-sign/e2e/                  testnet experiments (pnpm e2e) and demo backend smoke test
packages/kit-compat/                  c-sign in an application on stellar-sdk 16 with passkey-kit 0.14 and 0.20: tests and experiments
examples/quickstart/                  sign-in on testnet end to end: relying party and terminal wallet
packages/c-sign/scripts/vectors.ts    test-vector generator (pnpm vectors)
vectors/c-sign-v1.json                test vectors for other implementations
apps/demo/                            passkey sign-in demo (Vite, React, Vercel functions)
docs/SPEC.md                          draft SEP: "Signed Messages for Contract Accounts"
docs/SEP-43-CHANGE.md                 proposed wallet-interface change, separate from the SEP
docs/EXPERIMENTS.md                   testnet evidence with transaction links
docs/THREAT-MODEL.md                  threat model: trust assumptions, threats, tests, known gaps
docs/OVERVIEW.md                      project overview (source of C-Sign-Overview.pdf)
docs/ROADMAP.md                       plan and checkpoints
scripts/deploy-testnet.sh             testnet deployment (idempotent)
deployments/testnet.json              deployed ids, hashes and TTL
experiments/contracts/                fake-verifier (pinning), nonreverting-verifier (nonce) and ed25519-account (minimal account) fixtures

Build and test

cargo test                        # unit tests, native
stellar contract build --locked   # wasm: target/wasm32v1-none/release/sep53c_verifier.wasm
stellar contract info hash --wasm target/wasm32v1-none/release/sep53c_verifier.wasm   # must equal contracts/verifier/WASM_HASH

pnpm install
pnpm test                         # library and kit-compat unit tests, offline
pnpm --filter c-sign test:browser # library bundled for the browser, in headless Chrome
pnpm e2e                          # testnet experiments, rewrites docs/EXPERIMENTS.md
                                  # optional: RPC_URL (another provider), FUNDER_SECRET (if Friendbot is down)
pnpm vectors                      # regenerates vectors/c-sign-v1.json

The build is reproducible. Pinned inputs: rustc 1.96.1 (rust-toolchain.toml), soroban-sdk 28.0.0 (Cargo.lock) and stellar-cli 27.0.0, whose version is embedded in the Wasm metadata. CI checks the hash on every push. Enforcing simulation needs stellar-rpc 23 or newer and the authMode argument of simulateTransaction (js-stellar-sdk 14 or newer). The library uses js-stellar-sdk 17 and accepts entries and keys from 16 or 17; the demo uses 16.4, the version smart-account-kit expects.

Known limitations

  • Validity follows the account's current rules, as with ERC-1271: a signature stops verifying after signers or policies change.
  • Signature lifetime is bounded by max_entry_ttl (about 180 days on current network settings).
  • Verification trusts the RPC that runs the simulation, like ERC-1271 with eth_call. Use your own RPC or cross-check two providers.
  • Accounts that are not deployed yet cannot be verified.
  • Accounts whose context rules only allow specific contracts need a rule that covers the verifier.

License

Apache-2.0

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages